Enviar uma mensagem do WhatsApp

O que é

A API de Mensagens do WhatsApp envia mensagens de modelo, texto, imagem, vídeo, áudio, documento, figurinha, localização, interativas, de contato e de reação a partir de um número de telefone comercial do WhatsApp conectado.

Antes de começar

Armazene sua chave de API da YCloud em YCLOUD_API_KEY.
Conecte uma conta do WhatsApp Business e um número de telefone à YCloud.
Obtenha o número de telefone do remetente no formato E.164 e o número de telefone do destinatário, o BSUID ou o BSUID principal.
Use um modelo APPROVED para envios comuns de modelos.
Faça o upload da mídia primeiro quando a mensagem fizer referência a um ID de mídia da YCloud.

Como funciona

Escolha o endpoint com base em quando a YCloud deve enviar a mensagem para a WhatsApp Business API.

Endpoint	Comportamento	Usar para
`POST /whatsapp/messages`	Coloca a mensagem na fila e a envia de forma assíncrona.	A maioria dos fluxos de trabalho de mensagens de saída.
`POST /whatsapp/messages/sendDirectly`	Envia a mensagem de forma síncrona para a WhatsApp Business API.	OTP e outras mensagens com tempo crítico.

Ambos os endpoints retornam um objeto de mensagem da YCloud. A resposta inicial não confirma a entrega final. Alterações de status posteriores chegam por meio de Webhooks whatsapp.message.updated.

Envie sua primeira mensagem

Escolha um modelo aprovado pertencente à sua WABA conectada. Substitua o remetente, o destinatário, o nome do modelo e o idioma pelos seus próprios valores e envie:

curl --request POST https://api.ycloud.com/v2/whatsapp/messages \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "from": "+16315551111",
    "to": "+16315552222",
    "type": "template",
    "externalId": "welcome-10001",
    "template": {
      "name": "welcome_message",
      "language": { "code": "en_US" }
    }
  }'

Armazene o id retornado e acompanhe seus eventos de whatsapp.message.updated. Uma resposta accepted significa que a solicitação entrou em processamento, não que o cliente a recebeu. Configure tanto whatsapp.message.updated quanto whatsapp.inbound_message.received quando precisar de rastreamento de entrega e respostas.

Escolha um modelo ou mensagem de sessão

Use um modelo aprovado para mensagens comuns iniciadas pela empresa fora da janela de atendimento ao cliente. Dentro de uma janela aberta, use os tipos de mensagem livres suportados, como texto, mídia ou respostas interativas. Verifique as regras da janela de atendimento ao cliente no momento do envio. Uma janela de preços não substitui a elegibilidade para troca de mensagens. Consulte os preços do WhatsApp para ver as cobranças atuais e as condições dos pontos de entrada.

Envio Direto para conteúdo de utilidade

O Envio Direto pode enviar conteúdo de utilidade elegível ou converter um modelo de utilidade existente. Ele funciona com qualquer um dos endpoints de envio. O endpoint sendDirectly controla o envio síncrono; ele não ativa o Envio Direto por si só. Siga as práticas recomendadas do Envio Direto para elegibilidade, solicitações, conversão de modelos, limites e eventos da conta.

Escolha o melhor horário de envio

Alinhe o horário de envio à finalidade da mensagem e ao horário local do destinatário.

Envie OTPs e outras mensagens com tempo crítico imediatamente. Use POST /whatsapp/messages/sendDirectly quando o seu fluxo de trabalho precisar do resultado do envio antes de continuar.
Envie atualizações transacionais quando o evento relacionado ocorrer, como um pagamento, envio de mercadoria ou alteração de agendamento.
Agende mensagens de marketing para horários razoáveis no fuso horário do destinatário. Use seus próprios dados de entrega, leitura e conversão para testar diferentes intervalos de horário para cada público, em vez de presumir um único melhor horário universal.
Comece uma campanha agendada com um grupo pequeno de destinatários. Verifique a entrega, as respostas e as taxas de cancelamento (opt-out) antes de enviar para o restante do público.
Evite envios repetidos quando uma mensagem estiver atrasada. Armazene o externalId e processe Webhooks whatsapp.message.updated antes de decidir tentar novamente.

Solicitação

Escolha qualquer um dos endpoints acima e use o corpo da solicitação correspondente ao tipo de mensagem. O valor de from é o seu número de telefone comercial do WhatsApp conectado. Especifique o destinatário com to no formato E.164 ou com recipient definido como um BSUID ou BSUID principal.

Campos de solicitação comuns

Campo	Obrigatório	Descrição
`from`	Sim	Número de telefone comercial do WhatsApp conectado no formato E.164.
`to`	Condicional	Número de telefone do destinatário no formato E.164. Obrigatório quando `recipient` estiver ausente.
`recipient`	Condicional	BSUID ou BSUID principal do destinatário. Obrigatório quando `to` estiver ausente.
`type`	Sim	Tipo de mensagem. Inclua o campo de conteúdo correspondente a este valor.
`template`, `text`, `image` e outros campos de tipo	Condicional	Objeto de conteúdo obrigatório pelo `type` selecionado.
`context`	Não	Contexto da mensagem usado ao responder a uma mensagem anterior.
`externalId`	Não	Sua referência exclusiva para conciliar a mensagem com um registro interno.
`filterUnsubscribed`	Não	Somente enfileiramento. O padrão é `false`; quando `true`, filtra destinatários na lista de cancelamento de inscrição.
`filterBlocked`	Não	Somente enfileiramento. O padrão é `false`; quando `true`, filtra destinatários bloqueados.

filterUnsubscribed e filterBlocked aplicam-se apenas a POST /whatsapp/messages; eles não se aplicam a sendDirectly. Uma mensagem enfileirada filtrada falha com RECIPIENT_UNSUBSCRIBED ou RECIPIENT_IN_BLOCK_LIST em seu webhook de status. Para envios síncronos, aplique verificações de consentimento, cancelamento de inscrição e bloqueio em sua aplicação.

Forneça pelo menos um dentre to ou recipient. Se incluir ambos, a YCloud usará to e ignorará recipient.

Modelos de autenticação por um toque (one-tap), zero toque (zero-tap) e copiar código (copy-code) exigem um número de telefone. Use to para esses tipos de modelo.

Exemplos de requisição

Mensagem de modelo

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "template",
  "template": {
    "name": "sample_whatsapp_template",
    "language": {
      "code": "en",
      "policy": "deterministic"
    }
  }
}

Mensagem de texto

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "text",
  "text": {
    "body": "Hello from YCloud!"
  }
}

Mensagem de imagem

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "image",
  "image": {
    "id": "MEDIA_ID",
    "caption": "Product image"
  }
}

Mensagem de vídeo

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "video",
  "video": {
    "id": "MEDIA_ID",
    "caption": "Product video"
  }
}

Mensagem de áudio

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "audio",
  "audio": {
    "id": "MEDIA_ID"
  }
}

Mensagem de documento

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "document",
  "document": {
    "id": "MEDIA_ID",
    "filename": "invoice.pdf"
  }
}

Mensagem de figurinha

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "sticker",
  "sticker": {
    "id": "MEDIA_ID"
  }
}

Mensagem de localização

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "location",
  "location": {
    "latitude": 37.422,
    "longitude": -122.084,
    "name": "Googleplex",
    "address": "1600 Amphitheatre Pkwy, Mountain View, CA"
  }
}

Mensagem interativa

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "body": {
      "text": "Do you want to continue?"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "yes",
            "title": "Yes"
          }
        }
      ]
    }
  }
}

Mensagem de contatos

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "contacts",
  "contacts": [
    {
      "name": {
        "formatted_name": "John Smith"
      },
      "phones": [
        {
          "phone": "+16315551111",
          "type": "CELL"
        }
      ]
    }
  ]
}

Mensagem de reação

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "reaction",
  "reaction": {
    "message_id": "wamid.BgNODYxN...",
    "emoji": "👍"
  }
}

Adicionar variáveis de modelo

Faça a correspondência exata do nome do modelo, idioma e ordem dos parâmetros com o seu modelo aprovado. Para um corpo com parâmetros de nome do cliente e referência do pedido, envie:

{
  "from": "+16315551111",
  "to": "+16315552222",
  "type": "template",
  "template": {
    "name": "order_update",
    "language": { "code": "en_US" },
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "Alex" },
          { "type": "text", "text": "ORDER-10001" }
        ]
      }
    ]
  }
}

Consulte exemplos de mensagens de modelo para componentes e tipos de mensagem adicionais.

Responder a uma mensagem específica

Defina context.message_id com o ID da mensagem original do WhatsApp (wamid) para criar uma resposta citada. Continue verificando se a janela de atendimento ao cliente está aberta.

{
  "from": "+16315551111",
  "to": "+16315552222",
  "type": "text",
  "text": { "body": "Your order is ready for collection." },
  "context": { "message_id": "wamid.EXAMPLE" }
}

Aplicar filtros de cancelamento de inscrição e bloqueio

Para POST /whatsapp/messages, defina filterUnsubscribed: true e filterBlocked: true quando precisar aplicar suas listas de supressão da YCloud. Ambos têm como padrão false e não se aplicam a sendDirectly. Inspecione whatsappMessage.errorCode nos webhooks de status para RECIPIENT_UNSUBSCRIBED ou RECIPIENT_IN_BLOCK_LIST. Não espere um status filtered separado. Aplique a supressão em sua aplicação antes de usar sendDirectly. Use externalId para associar mensagens a um pedido ou outro registro interno. Trata-se de um campo de correlação, não de uma chave de idempotência do lado do servidor.

Resposta

Uma resposta bem-sucedida retorna o objeto de mensagem da YCloud. Um status: accepted inicial significa que a YCloud aceitou a solicitação de envio. Isso não significa que a mensagem foi enviada pela Meta ou entregue ao usuário do WhatsApp.

Exemplo de resposta

{
  "id": "MESSAGE_ID",
  "wabaId": "WHATSAPP_BUSINESS_ACCOUNT_ID",
  "from": "+16315551111",
  "to": "+16315552222",
  "type": "text",
  "status": "accepted",
  "externalId": "order-10001",
  "createTime": "2026-07-16T12:00:00.000Z"
}

Campos de resposta

Campo	Descrição
`id`	ID da mensagem na YCloud. Armazene-o para recuperação e correlação via Webhook.
`wamid`	ID original da mensagem no WhatsApp. Disponível após o envio para o WhatsApp.
`wabaId`	ID da conta do WhatsApp Business.
`from`, `to`	Números de telefone do remetente e do destinatário.
`type`	Tipo de conteúdo da mensagem.
`status`	Estado atual, como `accepted`, `sent`, `failed`, `delivered` ou `read`.
`errorCode`, `errorMessage`	Detalhes da falha na YCloud quando `status` for `failed`.
`whatsappApiError`	Erro retornado pela WhatsApp Business API quando disponível.
`externalId`	A referência fornecida na requisição.
`category`	Categoria do Direct Send, como `utility` para os exemplos de utilidade acima.
`ttlSeconds`	Tempo de vida da mensagem no Direct Send, quando definido na mensagem.
`totalPrice`, `currency`	Preço e moeda estimados ou finais da mensagem.
`createTime`, `sendTime`, `deliverTime`, `readTime`	Timestamps do ciclo de vida no formato RFC 3339.

Status de entrega

Assine Webhooks de whatsapp.message.updated para receber alterações de status posteriores, como sent, failed, delivered ou read. Use GET /whatsapp/messages/{id} quando precisar recuperar uma mensagem diretamente.

Para mensagens de mídia, primeiro faça upload do arquivo com POST /whatsapp/media/{phoneNumber}/upload e, em seguida, use o ID de mídia retornado no payload da mensagem.

Limites e solução de problemas

Envios comuns de modelo exigem um modelo APPROVED; modelos ARCHIVED não podem ser enviados como mensagens de modelo comuns.
Não repita uma solicitação aceita sem uma estratégia de idempotência. Uma requisição repetida pode enviar uma mensagem duplicada.
Use o status de id, wamid, externalId e do Webhook da YCloud ao investigar a entrega.
Inspecione whatsappApiError quando uma requisição direta atingir a Meta e a Meta rejeitá-la.

Para limites de taxa de transferência, consulte Limites de taxa.

Melhores práticas do Direct Send

Envie conteúdo de utilidade, converta modelos e monitore eventos de categoria e restrição.

Melhores práticas em produção

Projete sincronização de status, tentativas delimitadas, verificações de consentimento, reutilização de mídia e controles de taxa de transferência para uma integração em produção.

Usar IDs de usuário com escopo de negócios

Envie mensagens e chamadas por BSUID, solicite números de telefone, gerencie entradas da lista de contatos da Meta e processe campos de Webhook com BSUID.

Exemplos completos de integração

Para o fluxo de trabalho completo de criação de modelos e vinculação de variáveis, consulte Exemplos de criação de modelos e Exemplos de envio de mensagens. Use Tratamento de erros do WhatsApp para distinguir a rejeição de solicitações de falhas posteriores de entrega, e Implementação de receptor de Webhook para verificar assinaturas e aceitar atualizações de status de forma durável.

Primeiros passos

Guias

Endpoints

Webhooks

Enviar uma mensagem do WhatsApp

O que é

Antes de começar

Como funciona

Envie sua primeira mensagem

Escolha um modelo ou mensagem de sessão

Envio Direto para conteúdo de utilidade

Escolha o melhor horário de envio

Solicitação

Campos de solicitação comuns

Exemplos de requisição

Adicionar variáveis de modelo

Responder a uma mensagem específica

Aplicar filtros de cancelamento de inscrição e bloqueio

Resposta

Exemplo de resposta

Campos de resposta

Status de entrega

Limites e solução de problemas

Melhores práticas do Direct Send

Melhores práticas em produção

Usar IDs de usuário com escopo de negócios

Exemplos completos de integração

​O que é

​Antes de começar

​Como funciona

​Envie sua primeira mensagem

​Escolha um modelo ou mensagem de sessão

​Envio Direto para conteúdo de utilidade

​Escolha o melhor horário de envio

​Solicitação

​Campos de solicitação comuns

​Exemplos de requisição

​Adicionar variáveis de modelo

​Responder a uma mensagem específica

​Aplicar filtros de cancelamento de inscrição e bloqueio

​Resposta

​Exemplo de resposta

​Campos de resposta

​Status de entrega

​Limites e solução de problemas

Melhores práticas do Direct Send

Melhores práticas em produção

Usar IDs de usuário com escopo de negócios

​Exemplos completos de integração

O que é

Antes de começar

Como funciona

Envie sua primeira mensagem

Escolha um modelo ou mensagem de sessão

Envio Direto para conteúdo de utilidade

Escolha o melhor horário de envio

Solicitação

Campos de solicitação comuns

Exemplos de requisição

Adicionar variáveis de modelo

Responder a uma mensagem específica

Aplicar filtros de cancelamento de inscrição e bloqueio

Resposta

Exemplo de resposta

Campos de resposta

Status de entrega

Limites e solução de problemas

Exemplos completos de integração