Enviar mensagem no WhatsApp, por uma API

Envia uma mensagem de um número de telefone comercial e retorna seu id em messages[0].id. Os tipos livres (text, image, video, document, audio) só chegam a quem escreveu para o número nas últimas 24 horas; para iniciar uma conversa, envie o tipo template com um template aprovado de Listar templates de mensagem. A Meta cobra as mensagens da conta conforme seus preços do WhatsApp.

Identificador
whatsapp_send_message

A chamada

POST https://connect.reportei.com/api/tools/whatsapp_send_message/execute
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Content-Type: application/json
Accept: application/json

{
  "customer_toolkit": "<connection UUID>",
  "arguments": {
    "phone_number_id": "<phone_number_id>",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "<recipient_number_with_country_code>",
    "type": "text",
    "text": {
      "body": "Hello! This is an example message.",
      "preview_url": false
    }
  }
}

Seu sistema envia o id da conexão do cliente e os argumentos da tool. Os headers são os mesmos de toda a API do Connect: o token do seu produto e o token do cliente.

Exemplo ilustrativo. Substitua os tokens, o UUID da conexão e os dados de destino pelos seus. Esta página não executa a chamada.

Antes de executar

  • Para type=text, envie text.body. O número de destino deve conter código do país e apenas dígitos. Use o phone_number_id da conta comercial conectada.
  • Texto livre atende conversas dentro da janela de 24 horas após a mensagem do usuário. Para iniciar uma conversa fora dela, use type=template e um template aprovado, com language e os parâmetros exigidos pelo template.
  • O ID retornado identifica a mensagem aceita pela API; não confirma entrega. Confira o corpo de eventuais erros do provedor em api_error.body.

Parâmetros

As descrições dos parâmetros seguem a documentação oficial do app, em inglês.

ParâmetroTipoObrigatórioDescrição
phone_number_idstringSimId of the business phone number that sends, from List phone numbers.
messaging_productstringSimAlways whatsapp.Valores: whatsapp
recipient_typestringSimindividual for a person, group for a WhatsApp group of the number.Valores: individual, group
tostringSimPhone number of the person with country code, digits only, for example 5511987654321, or the id of the group.
typestringSimKind of message. Send the object with the same name, such as text or template.Valores: text, template, image, video, document, audio
textobjectSim, se type=textFor type text.
templateobjectSim, se type=templateFor type template.
imageobjectSim, se type=imageFor type image: a JPEG or PNG at a public URL.
videoobjectSim, se type=videoFor type video: an MP4 or 3GP at a public URL.
documentobjectSim, se type=documentFor type document: a file at a public URL, such as a PDF.
audioobjectSim, se type=audioFor type audio: an audio file at a public URL.

Conexões possíveis

O seu cliente conecta a conta do WhatsApp uma vez, por um dos modos abaixo. A mesma conexão serve para todas as tools do toolkit.

Chave de API

O cliente cola a chave do app numa tela do Connect, ou o seu sistema envia a chave por POST /api/customer-toolkits, sem tela.

A resposta

Em caso de sucesso, o Connect preserva o status e o corpo da resposta do app. Erros HTTP retornados pelo app usam o envelope {error, api_error}; falhas de autenticação ou validação podem ocorrer antes da execução. O header X-Toolkit-Execution-Id identifica a execução registrada, consultável em GET /api/tools/executions/{uuid}.

Formato ilustrativo de sucesso

{
  "messaging_product": "whatsapp",
  "messages": [
    {
      "id": "wamid.EXAMPLE"
    }
  ]
}

O conteúdo abaixo é um exemplo, não o resultado de uma execução. Guarde o X-Toolkit-Execution-Id quando retornado para consultar a execução. O Connect não aplica retry nem idempotência: repetir um POST pode repetir o envio.

Pronta para agentes de IA

O input desta tool é um JSON Schema, disponível em GET /api/tools/whatsapp_send_message. Ele vira a definição de tool do seu agente sem conversão.

Outras tools do WhatsApp

Ver as 10 tools

Toolkits da mesma categoria

Ver os 100 toolkits

Veja o Connect aplicado ao seu produto.

Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.