Enviar uma mensagem do WhatsApp

O que é

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

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.
Colete o número de telefone do remetente no formato E.164 e o número de telefone do destinatário, BSUID ou BSUID pai.
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	Use para
`POST /whatsapp/messages`	Enfileira a mensagem e a envia de forma assíncrona.	A maioria dos fluxos de envio de mensagens ativas.
`POST /whatsapp/messages/sendDirectly`	Envia a mensagem de forma síncrona para a WhatsApp Business API.	OTP e outras mensagens sensíveis ao tempo.

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.

Direct Send para conteúdo de utilidade

O Direct Send pode enviar conteúdo de utilidade qualificado 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 Direct Send por si só. Siga as melhores práticas do Direct Send para qualificação, solicitações, conversão de modelos, limites e eventos de conta.

Escolha o melhor momento de envio

Combine o horário de envio com a finalidade da mensagem e o horário local do destinatário.

Envie OTPs e outras mensagens sensíveis ao tempo imediatamente. Use POST /whatsapp/messages/sendDirectly quando 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 tempo para cada público, em vez de assumir um único melhor horário universal.
Inicie uma campanha agendada com um grupo pequeno de destinatários. Verifique a entrega, a resposta e os resultados de cancelamento de inscrição antes de enviar para o restante do público.
Evite envios repetidos quando uma mensagem estiver atrasada. Armazene externalId e processe os Webhooks whatsapp.message.updated antes de decidir tentar novamente.

Requisição

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

Campos comuns de requisição

Campo	Obrigatório	Descrição
`from`	Sim	Número de telefone comercial conectado do WhatsApp 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 pai 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 exigido 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	Apenas no enfileiramento. O padrão é `false`; quando for `true`, filtra destinatários na lista de cancelamento de inscrição.
`filterBlocked`	Não	Apenas no enfileiramento. O padrão é `false`; quando for `true`, filtra destinatários bloqueados.

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

Forneça pelo menos um entre to ou recipient. Se incluir ambos, a YCloud usa to e ignora recipient.

Modelos de autenticação de um toque (one-tap), toque zero (zero-tap) e cópia de código requerem 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": "👍"
  }
}

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 da resposta

Campo	Descrição
`id`	ID da mensagem na YCloud. Armazene-o para recuperação e correlação de Webhook.
`wamid`	ID original da mensagem do 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 solicitação.
`category`	Categoria do Direct Send, como `utility` para os exemplos de utilidade acima.
`ttlSeconds`	Tempo de vida da mensagem Direct Send, quando definido na mensagem.
`totalPrice`, `currency`	Preço estimado ou final da mensagem e moeda.
`createTime`, `sendTime`, `deliverTime`, `readTime`	Carimbos de data/hora do ciclo de vida no formato RFC 3339.

Status de entrega

Inscreva-se nos 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, faça o upload do arquivo primeiro 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 normais de modelos exigem um modelo APPROVED; modelos ARCHIVED não podem ser enviados como mensagens de modelo comuns.
Não tente reenviar uma solicitação aceita sem uma estratégia de idempotência. Uma solicitação repetida pode enviar uma mensagem duplicada.
Use o status de id, wamid, externalId da YCloud e do Webhook ao investigar a entrega.
Inspecione whatsappApiError quando uma solicitação direta chegar à 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 para produção

Projete sincronização de status, repetições limitadas, 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 (BSUID)

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

Exemplos completos de integração

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

Primeiros passos

Guias

Endpoints

Webhooks

Enviar uma mensagem do WhatsApp

O que é

Antes de começar

Como funciona

Direct Send para conteúdo de utilidade

Escolha o melhor momento de envio

Requisição

Campos comuns de requisição

Exemplos de requisição

Resposta

Exemplo de resposta

Campos da resposta

Status de entrega

Limites e solução de problemas

Melhores práticas do Direct Send

Melhores práticas para produção

Usar IDs de usuário com escopo de negócios (BSUID)

Exemplos completos de integração

​O que é

​Antes de começar

​Como funciona

​Direct Send para conteúdo de utilidade

​Escolha o melhor momento de envio

​Requisição

​Campos comuns de requisição

​Exemplos de requisição

​Resposta

​Exemplo de resposta

​Campos da resposta

​Status de entrega

​Limites e solução de problemas

Melhores práticas do Direct Send

Melhores práticas para produção

Usar IDs de usuário com escopo de negócios (BSUID)

​Exemplos completos de integração

O que é

Antes de começar

Como funciona

Direct Send para conteúdo de utilidade

Escolha o melhor momento de envio

Requisição

Campos comuns de requisição

Exemplos de requisição

Resposta

Exemplo de resposta

Campos da resposta

Status de entrega

Limites e solução de problemas

Exemplos completos de integração