Pular para o conteúdo principal

[Alpha] Como configurar a API de fallback de WhatsApp para Google RCS

  • Atualizado
  1. Resumo
  2. Contrato de dados comum
  3. Passos para integração
  4. Dicas e validações

 

Resumo

A funcionalidade de fallback permite recuperar a entrega de mensagens em campanhas ativas. O processo avalia as tentativas de envio do canal principal e copia automaticamente os destinatários elegíveis cujas entregas falharam para uma campanha secundária no canal de destino. Este guia é restrito à integração onde o canal principal é o WhatsApp e o canal de fallback é o GoogleRCS.

Antes de começar

  • Canal Principal: WHATSAPP.

  • Canal de Fallback: GoogleRCS.

  • Endpoint de Comandos LIME: POST https://<owner-domain>/commands

  • Identidade do Serviço Active Campaign: postmaster@activecampaign.msging.net

  • Autenticação: Header Authorization: Key <auth-key>

  • Identificador Único: Todo comando enviado deve conter um parâmetro id exclusivo.

  • Correspondência de Tipos: O atributo type do recurso no envelope da requisição deve corresponder exatamente ao tipo de recurso enviado.

  • Avaliação Sequencial: O fallback é avaliado após o disparo da campanha principal; ele não é executado como uma segunda campanha paralela.

 

Contrato de dados comum

Fallback da campanha

A estrutura de fallback é declarada dentro do objeto campaign:

{
  "fallback": {
    "channelType": "GoogleRCS",
    "message": {
      "channelType": "GoogleRCS",
      "messageContent": "Olá ${contact.extras.name}, sua mensagem de WhatsApp não foi entregue.",
      "messageParams": ["name"]
    }
  }
}

  • O objeto fallback.message é obrigatório sempre que o objeto fallback estiver presente na requisição.

  • A mensagem do fallback deve utilizar o mesmo canal configurado em fallback.channelType.

  • Enquanto a mensagem principal em uma campanha de WhatsApp utiliza um template aprovado, a mensagem de fallback é independente e deve ser criada especificamente para o canal Google RCS.

Detalhamento dos Campos:

  • fallback.channelType (Obrigatório): Deve ser preenchido como "GoogleRCS".

  • fallback.message.channelType (Obrigatório): Deve ser exatamente igual a fallback.channelType ("GoogleRCS").

  • fallback.message.messageContent (Obrigatório): Texto/corpo da mensagem que será enviada no canal RCS.

  • fallback.message.messageParams (Opcional): Lista com os nomes dos parâmetros dinâmicos referenciados em messageContent.

Parâmetros dinâmicos

Sempre que o texto em messageContent contiver variáveis no formato ${contact.extras.<name>}, declare os nomes correspondentes na lista messageParams:

{
  "messageContent": "Olá ${contact.extras.name}. Acompanhe em ${contact.extras.url}.",
  "messageParams": ["name", "url"]
}

  • O registro da audiência fornecerá os valores para preenchimento dos parâmetros declarados em messageParams.

Envelope de comando LIME

Todas as chamadas operam utilizando a estrutura do envelope LIME abaixo:

{
  "id": "<unique-command-id>",
  "to": "postmaster@activecampaign.msging.net",
  "method": "set",
  "uri": "<resource-uri>",
  "type": "<resource-media-type>",
  "resource": {}
}

  • method: Utilize "set" para criar, atualizar e disparar recursos. Utilize "get" para leitura de recursos e "delete" para remoção.

 

Passos para integração

Você pode realizar a integração através de dois fluxos operacionais: Fluxo Incremental (passo a passo) ou Fluxo Completo (operação única).

Fluxo Incremental

Passo 1: Criar a campanha em /campaigns

Utilize este procedimento para registrar a campanha e armazenar a configuração de fallback. Esta etapa não cria as mensagens nem a audiência.

  • URI: /campaigns

  • Type: application/vnd.iris.activecampaign.campaign+json

Requisição:

curl --request POST \
  --url https://<owner-domain>/commands \
  --header 'Authorization: Key <auth-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "c2f2d9d0-2c8a-4f6a-bb58-0fcb1c17c401",
    "to": "postmaster@activecampaign.msging.net",
    "method": "set",
    "uri": "/campaigns",
    "type": "application/vnd.iris.activecampaign.campaign+json",
    "resource": {
      "name": "Campanha WhatsApp com fallback RCS",
      "channelType": "WHATSAPP",
      "campaignType": "INDIVIDUAL",
      "fallback": {
        "channelType": "GoogleRCS",
        "message": {
          "channelType": "GoogleRCS",
          "messageContent": "Olá ${contact.extras.name}, sua mensagem de WhatsApp não foi entregue.",
          "messageParams": ["name"]
        }
      }
    }
  }'

  • Importante: Guarde o id da campanha retornado na resposta da requisição. Ele será utilizado nos passos seguintes (/messages, /audiences e /dispatch).

Passo 2: Configurar a mensagem principal em /messages

Adicione o template de mensagem que será utilizado pelo canal principal (WhatsApp).

  • URI: /messages/<campaign-id>

  • Type: application/vnd.iris.activecampaign.message+json

Requisição:

curl --request POST \
  --url https://<owner-domain>/commands \
  --header 'Authorization: Key <auth-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "c2f2d9d0-2c8a-4f6a-bb58-0fcb1c17c402",
    "to": "postmaster@activecampaign.msging.net",
    "method": "set",
    "uri": "/messages/<campaign-id>",
    "type": "application/vnd.iris.activecampaign.message+json",
    "resource": {
      "channelType": "WHATSAPP",
      "messageTemplate": "pedido_entregue",
      "messageTemplateLanguage": "pt_BR"
    }
  }'

  • Atenção: Não envie a mensagem de fallback nesta chamada; a mensagem do canal RCS já foi armazenada no cadastro da campanha (Passo 1).

  • Consultas: Para consultar mensagens cadastradas em uma campanha, envie um comando get para a URI /messages/{campaignId} ou /messages/{campaignId}/{channelType}.

Passo 3: Adicionar destinatários em /audiences

Cadastre a audiência da campanha principal. O canal informado nos registros de audiência deve corresponder ao canal principal (WHATSAPP).

  • URI: /audiences/<campaign-id>

Opção A: Destinatário único

  • Type: application/vnd.iris.activecampaign.audience+json

curl --request POST \
  --url https://<owner-domain>/commands \
  --header 'Authorization: Key <auth-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "c2f2d9d0-2c8a-4f6a-bb58-0fcb1c17c403",
    "to": "postmaster@activecampaign.msging.net",
    "method": "set",
    "uri": "/audiences/<campaign-id>",
    "type": "application/vnd.iris.activecampaign.audience+json",
    "resource": {
      "recipient": "+5511999999999",
      "recipientType": "PhoneNumber",
      "channelType": "WHATSAPP",
      "messageParams": {
        "name": "Maria"
      }
    }
  }'
Opção B: Vários destinatários (Coleção LIME)

  • Type: application/vnd.lime.collection+json

{
  "id": "c2f2d9d0-2c8a-4f6a-bb58-0fcb1c17c404",
  "to": "postmaster@activecampaign.msging.net",
  "method": "set",
  "uri": "/audiences/<campaign-id>",
  "type": "application/vnd.lime.collection+json",
  "resource": {
    "itemType": "application/vnd.iris.activecampaign.audience+json",
    "items": [
      {
        "recipient": "+5511999999999",
        "recipientType": "PhoneNumber",
        "channelType": "WHATSAPP",
        "messageParams": {
          "name": "Maria"
        }
      },
      {
        "recipient": "+5511888888888",
        "recipientType": "PhoneNumber",
        "channelType": "WHATSAPP",
        "messageParams": {
          "name": "João"
        }
      }
    ]
  }
}

  • Regra de Audiência: O mecanismo de fallback remapeia automaticamente a audiência elegível para o canal Google RCS. Não crie uma segunda audiência de fallback manualmente.

Passo 4: Executar o disparo em /dispatch

Inicie o envio da campanha. Quando o fallback estiver configurado, a execução do disparo agenda a verificação automática de falhas.

  • URI: /dispatch (ou /dispatch/v2 para campanhas dinâmicas)

  • Type: application/vnd.iris.activecampaign.campaign+json

Requisição:

curl --request POST \
  --url https://<owner-domain>/commands \
  --header 'Authorization: Key <auth-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "c2f2d9d0-2c8a-4f6a-bb58-0fcb1c17c405",
    "to": "postmaster@activecampaign.msging.net",
    "method": "set",
    "uri": "/dispatch",
    "type": "application/vnd.iris.activecampaign.campaign+json",
    "resource": {
      "id": "<campaign-id>"
    }
  }'

  • Opções Adicionais: É possível incluir as propriedades isToUseLiteApi, canSendWithOpenTicket e usersFilter dentro de resource caso sua operação exija.

Fluxo Completo (Criação e disparo em requisição única)

Operação via /campaign/full

Este endpoint cria a campanha, define a mensagem principal, cadastra a audiência e pode realizar o disparo de forma simultânea. Suporta os tipos de campanha INDIVIDUAL, GROUP, BATCH, USERSFILTER e FROMCAMPAIGN.

  • URI: /campaign/full

  • Type: application/vnd.iris.activecampaign.full-campaign+json

Requisição:

curl --request POST \
  --url https://<owner-domain>/commands \
  --header 'Authorization: Key <auth-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "c2f2d9d0-2c8a-4f6a-bb58-0fcb1c17c406",
    "to": "postmaster@activecampaign.msging.net",
    "method": "set",
    "uri": "/campaign/full",
    "type": "application/vnd.iris.activecampaign.full-campaign+json",
    "resource": {
      "campaign": {
        "name": "Fallback de WhatsApp para RCS",
        "channelType": "WHATSAPP",
        "campaignType": "INDIVIDUAL",
        "fallback": {
          "channelType": "GoogleRCS",
          "message": {
            "channelType": "GoogleRCS",
            "messageContent": "Olá ${contact.extras.name}, estamos enviando sua mensagem por RCS.",
            "messageParams": ["name"]
          }
        }
      },
      "message": {
        "channelType": "WHATSAPP",
        "messageTemplate": "pedido_entregue",
        "messageTemplateLanguage": "pt_BR"
      },
      "audiences": [
        {
          "recipient": "+5511999999999",
          "recipientType": "PhoneNumber",
          "channelType": "WHATSAPP",
          "messageParams": {
            "name": "Maria"
          }
        }
      ],
      "dispatch": true
    }
  }'

  • Defina "dispatch": false caso deseje criar a estrutura completa sem realizar o disparo imediato.

Operação via /campaign/full/v2

Utilizado para o fluxo dinâmico de campanhas em lote (BATCH) ou por filtro de usuários (USERSFILTER).

  • URI: /campaign/full/v2

  • Type: application/vnd.iris.activecampaign.full-campaign+json

Exemplo com envio BATCH:

{
  "id": "c2f2d9d0-2c8a-4f6a-bb58-0fcb1c17c407",
  "to": "postmaster@activecampaign.msging.net",
  "method": "set",
  "uri": "/campaign/full/v2",
  "type": "application/vnd.iris.activecampaign.full-campaign+json",
  "resource": {
    "campaign": {
      "name": "Lote WhatsApp com fallback RCS",
      "channelType": "WHATSAPP",
      "campaignType": "BATCH",
      "fileUrl": "https://<media-host>/audience.csv",
      "fallback": {
        "channelType": "GoogleRCS",
        "message": {
          "channelType": "GoogleRCS",
          "messageContent": "Olá ${contact.extras.name}, sua mensagem está sendo reenviada por RCS.",
          "messageParams": ["name"]
        }
      }
    },
    "message": {
      "channelType": "WHATSAPP",
      "messageTemplate": "pedido_entregue",
      "messageTemplateLanguage": "pt_BR"
    },
    "dispatch": true
  }
}

  • Em campanhas do tipo BATCH, a lista de contatos é fornecida via campo fileUrl.

 

Dicas e validações

Erros comuns e regras de validação

A API rejeitará a requisição se qualquer uma das regras abaixo for violada:

  1. Presença do objeto fallback sem a propriedade fallback.message.

  2. Divergência entre fallback.message.channelType e fallback.channelType.

  3. Definição do canal de fallback idêntico ao canal principal da campanha.

  4. Valor de fallback.channelType diferente de GoogleRCS.

  5. Canal principal da campanha (campaign.channelType) diferente de WHATSAPP.

  6. Canal da mensagem principal diferente de campaign.channelType.

  7. Registros em audiences configurados com canal diferente do canal principal.

  8. Configuração de mais de um canal de fallback na mesma requisição.

Importante: Configure obrigatoriamente o fallback antes do disparo. O envio de dados de fallback após o início do processamento da campanha principal não é suportado e pode gerar inconsistências.

Acompanhamento da execução

  • A campanha de fallback é gerada e disparada automaticamente pelo serviço após o término do período de tolerância das falhas detectadas no canal principal.

  • Utilize as operações de consulta (get) nos endpoints de campanhas e audiências para monitorar tanto a execução da campanha principal quanto a da campanha de fallback criada pelo sistema.

  • Não crie nem gerencie manualmente a campanha secundária de fallback.
     

 

Precisa de mais ajuda? Explore nossos conteúdos na Blip Academy ou Blip Community, assista a tutoriais no nosso canal do YouTube ou tire suas dúvidas em nosso canal de atendimento 😃

Artigos relacionados