> ## Documentation Index > Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt > Use this file to discover all available pages before exploring further. # Enviar uma mensagem do WhatsApp > Envie mensagens de modelo, sessão e mídia do WhatsApp com a API enfileirada ou síncrona. ## 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](/pt/api-reference/guides/whatsapp-platform/best-practices/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 ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "from": "+16315551111", "to": "+16315551111", "type": "template", "template": { "name": "sample_whatsapp_template", "language": { "code": "en", "policy": "deterministic" } } } ``` ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "from": "+16315551111", "to": "+16315551111", "type": "text", "text": { "body": "Hello from YCloud!" } } ``` ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "from": "+16315551111", "to": "+16315551111", "type": "image", "image": { "id": "MEDIA_ID", "caption": "Product image" } } ``` ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "from": "+16315551111", "to": "+16315551111", "type": "video", "video": { "id": "MEDIA_ID", "caption": "Product video" } } ``` ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "from": "+16315551111", "to": "+16315551111", "type": "audio", "audio": { "id": "MEDIA_ID" } } ``` ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "from": "+16315551111", "to": "+16315551111", "type": "document", "document": { "id": "MEDIA_ID", "filename": "invoice.pdf" } } ``` ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "from": "+16315551111", "to": "+16315551111", "type": "sticker", "sticker": { "id": "MEDIA_ID" } } ``` ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "from": "+16315551111", "to": "+16315551111", "type": "location", "location": { "latitude": 37.422, "longitude": -122.084, "name": "Googleplex", "address": "1600 Amphitheatre Pkwy, Mountain View, CA" } } ``` ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "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" } } ] } } } ``` ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "from": "+16315551111", "to": "+16315551111", "type": "contacts", "contacts": [ { "name": { "formatted_name": "John Smith" }, "phones": [ { "phone": "+16315551111", "type": "CELL" } ] } ] } ``` ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "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 ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "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](/pt/api-reference/guides/api-fundamentals/rate-limits). Envie conteúdo de utilidade, converta modelos e monitore eventos de categoria e restriçã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. 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](/pt/api-reference/guides/examples/api-examples/whatsapp-template-creation-examples) e [Exemplos de mensagens](/pt/api-reference/guides/examples/api-examples/whatsapp-messaging-examples). Use o [Tratamento de erros do WhatsApp](/pt/api-reference/guides/whatsapp-platform/handle-whatsapp-errors) para distinguir a rejeição de solicitações de falhas de entrega posteriores, e [Implementação de receptor de Webhook](/pt/api-reference/guides/api-fundamentals/implement-a-webhook-receiver) para verificar assinaturas e aceitar atualizações de status de forma duradoura. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.