Enviando Mensagens

O Fiwano tem quatro endpoints de envio — texto simples, mídia, mensagens interativas (botões, cards, respostas rápidas, listas) e modelos do WhatsApp. Todos recebem um channel_id e um recipient. O formato do recipient depende do canal (número de telefone para WhatsApp, IGSID para Instagram, PSID para Facebook) — veja a linha de destinatário em Capacidades. Os schemas completos de request/response estão na Referência da API; esta página é o guia por tarefa.

Enviar mensagens de WhatsApp com a API

Para uma resposta normal de WhatsApp dentro da janela de atendimento de 24 horas, use o endpoint de texto simples abaixo com um channel_id de WhatsApp e o número de telefone do destinatário. Você autentica com sua X-API-Key da Fiwano; não precisa de uma chave separada da API da Meta ou do WhatsApp na sua aplicação.

Fora da janela de 24 horas, o WhatsApp exige uma mensagem de template aprovada. Isso usa /api/v1/messages/send-template e está descrito em Modelos do WhatsApp. Instagram DM e Facebook Messenger usam o mesmo endpoint de texto para respostas comuns, com IGSID ou PSID como recipient.

Mensagens de texto

POST /api/v1/messages/send — funciona em todos os tipos de canal.

curl -X POST https://fiwano.com/api/v1/messages/send \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"channel_id": "a1b2c3d4e5f67890", "recipient": "1234567890", "text": "Hello! Your order is ready."}'

A resposta carrega um message_id (um UUID do Fiwano) que todo webhook posterior de status de entrega referencia. O texto tem um limite de tamanho por plataforma (WhatsApp 4096, Facebook 2000, Instagram 1000) — texto acima do limite é rejeitado com 400 text_too_long antes de chamar a Meta. O Fiwano não divide automaticamente; divida do seu lado para preservar seu próprio fatiamento e ordenação. Um text vazio ou só com espaços é rejeitado com 422.

Um recipient obviamente inválido (vazio, sem dígitos ou um PSID/IGSID não numérico) é rejeitado com 400 invalid_recipient antes de chamar a Meta; qualquer outro número de WhatsApp é passado à Meta como está, e a rejeição da própria Meta volta como status: "failed". Veja Erros HTTP.

Mensagens de mídia

POST /api/v1/messages/send-media — licença Pro obrigatória. A Meta busca o arquivo diretamente de media_url. Passe media_type (image, audio, video, document ou sticker — veja Figurinhas) e uma media_url HTTPS.

Use uma URL assinada para conteúdo não público — pré-assinada de S3/GCS/R2, SAS do Azure ou uma URL assinada por HMAC no seu próprio servidor, com expiração ≥ 20 min para continuar válida durante as novas tentativas em segundo plano. Uma URL pública é acessível por qualquer um que a descubra.

Mantenha os arquivos pequenos e a hospedagem rápida. A Meta baixa o arquivo enquanto sua requisição espera: uma imagem comprimida em um host rápido é aceita em poucos segundos, enquanto um arquivo grande em um host lento pode levar um minuto ou mais. Arquivos menores significam entrega mais rápida e previsível e menos envios concluídos em segundo plano — veja Tempo de resposta.

curl -X POST https://fiwano.com/api/v1/messages/send-media \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "channel_id": "a1b2c3d4e5f67890",
    "recipient": "1234567890",
    "media_type": "image",
    "media_url": "https://my-bucket.s3.amazonaws.com/photo.jpg?X-Amz-Signature=...&X-Amz-Expires=1800",
    "caption": "Your order photo"
  }'

caption (até 1024 caracteres) e filename (até 255) são campos do WhatsApp: caption aparece abaixo de um image, video ou document, e filename dá nome a um document. Em qualquer outro caso eles são aceitos e ignorados — um audio ou uma figurinha no WhatsApp não têm legenda, e no Instagram e no Messenger um anexo não leva nenhum dos dois: o arquivo chega sozinho, com o nome tirado da URL. Para acrescentar texto ali, envie-o com /messages/send antes ou depois do arquivo.

Sempre verifique success e status. Falhas permanentes incluem um error_code da Meta — por exemplo 131052 quando a Meta não consegue baixar a URL; as temporárias, como 131053, retornam queued e são repetidas como o texto. Os limites de tamanho de arquivo estão em Capacidades e a tabela completa de error codes está em Erros.

Figurinhas

media_type: "sticker" envia uma figurinha (sticker); o que ela exige depende do canal, porque as plataformas da Meta são diferentes:

curl -X POST https://fiwano.com/api/v1/messages/send-media \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"channel_id": "a1b2c3d4e5f67890", "recipient": "1234567890",
       "media_type": "sticker", "media_url": "https://my-bucket.s3.amazonaws.com/obrigado.webp?X-Amz-Signature=..."}'

caption e filename são ignorados em figurinhas. O campo errado para o canal — sticker_id no WhatsApp, media_url no Messenger, qualquer figurinha no Instagram — responde 400 invalid_media_request antes de chamar a Meta (reason diz qual). Um WebP que viola as regras do WhatsApp, ou um WebP enviado como image, falha na hora com o código 131053 da Meta e uma dica; não há nova tentativa. Uma figurinha recebida chega como image — com media.sticker: true no WhatsApp e no Messenger, como um GIF comum no Instagram — veja Recebendo Mensagens.

Tempo de resposta

POST /messages/send-media é síncrono e pode ser lento. O Fiwano nunca baixa seu arquivo: entregamos a media_url à Meta e a Meta busca o arquivo dentro da sua requisição. A espera é portanto proporcional ao tamanho do arquivo e à velocidade da sua própria hospedagem. Uma chamada de 12 segundos para um arquivo grande é normal. O Fiwano aguarda a Meta por até 30 segundos; se a Meta ainda não tiver respondido, a chamada retorna queued e o Fiwano conclui o envio em segundo plano — veja Entrega e novas tentativas.

Mensagens interativas com cards se comportam da mesma forma, porque a Meta baixa a imagem de cada card. Envios de texto, de modelo e os demais interativos não carregam arquivo e costumam completar em bem menos de um segundo.

Configure o timeout do seu cliente HTTP para pelo menos 35 segundos em send-media e em send-interactive com cards. Alguns ambientes limitam isso por você e não conseguem esperar tanto — o AWS API Gateway para em 29 segundos, e funções serverless costumam ter padrão de 10–15 segundos.

Se o seu cliente atingir o timeout, a mensagem ainda pode ter sido enviada. A Meta pode aceitá-la depois que você parou de esperar. Reenviar então entrega a mensagem duas vezes. Só tente novamente após confirmar que a mensagem não está na conversa.

Para manter os envios de mídia rápidos, sirva a media_url de um armazenamento próximo aos seus usuários (S3/GCS/R2 com CDN) e mantenha os arquivos bem abaixo dos limites de tamanho.

Mensagens interativas

POST /api/v1/messages/send-interactive — licença Pro obrigatória. Uma mensagem que o usuário responde com um toque: botões de resposta, um botão de link, cards no estilo de produto, chips de resposta rápida ou uma lista do WhatsApp. O mesmo formato de requisição funciona em todos os canais; cada canal recebe sua própria mensagem nativa. Como o texto, as mensagens interativas são enviadas dentro da janela de 24 horas — fora dela, no WhatsApp, use um modelo com botões de resposta rápida.

Envie text e exatamente um destes:

Um botão é {"type": "reply", "id": "...", "title": "..."} — o toque devolve o title para você — ou {"type": "url", "title": "...", "url": "https://..."}, que abre o link e não envia nada. title tem até 20 caracteres, id até 256 e é único na mensagem.

curl -X POST https://fiwano.com/api/v1/messages/send-interactive \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "channel_id": "a1b2c3d4e5f67890",
    "recipient": "1234567890",
    "text": "Qual tamanho você precisa?",
    "buttons": [
      {"type": "reply", "id": "size:P", "title": "P"},
      {"type": "reply", "id": "size:M", "title": "M"},
      {"type": "reply", "id": "size:G", "title": "G"}
    ]
  }'

Cards — cada um precisa de uma image_url HTTPS (JPEG ou PNG), um title (até 80 caracteres, uma linha), um subtitle opcional (até 80) e 1–3 botões:

curl -X POST https://fiwano.com/api/v1/messages/send-interactive \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "channel_id": "b2c3d4e5f6789012",
    "recipient": "17841400000000000",
    "cards": [
      {"image_url": "https://cdn.example.com/capa-de-chuva.jpg",
       "title": "Capa de chuva", "subtitle": "R$ 189 · tamanhos P–GG",
       "buttons": [
         {"type": "reply", "id": "add_to_cart:SKU-1", "title": "Adicionar"},
         {"type": "url", "title": "Ver no site", "url": "https://loja.example.com/p/1"}
       ]},
      {"image_url": "https://cdn.example.com/moletom.jpg",
       "title": "Moletom", "subtitle": "R$ 129 · tamanhos P–G",
       "buttons": [
         {"type": "reply", "id": "add_to_cart:SKU-2", "title": "Adicionar"},
         {"type": "url", "title": "Ver no site", "url": "https://loja.example.com/p/2"}
       ]}
    ]
  }'

Respostas rápidas (Instagram, Messenger) e uma lista (WhatsApp):

{"channel_id": "c3d4e5f678901234", "recipient": "25550000000000000",
 "text": "Escolha uma cor", "quick_replies": [
   {"id": "colour:red", "title": "Vermelho"}, {"id": "colour:blue", "title": "Azul"}]}

{"channel_id": "a1b2c3d4e5f67890", "recipient": "1234567890",
 "text": "Como prefere receber?", "list": {"button": "Opções", "sections": [
   {"title": "Entrega", "rows": [
     {"id": "ship:express", "title": "Expressa", "description": "Amanhã, R$ 19"},
     {"id": "ship:standard", "title": "Padrão", "description": "3–5 dias, grátis"}]}]}}

Quando o usuário toca um botão de resposta, um chip ou uma linha da lista, você recebe um message.received de type: "text" cujo text é o rótulo e button_id é o id que você definiu. Respostas digitadas e toques passam pelo mesmo handler.

O que muda por canal. São regras da Meta; o Fiwano as verifica antes de chamar a Meta e responde 400 invalid_interactive_request com um reason e uma hint, em vez de enviar algo diferente do que você pediu:

O Instagram mostra cards e respostas rápidas apenas no app para celular, não em instagram.com. A Meta baixa as imagens dos cards enquanto sua requisição aguarda, como na mídia: mantenha-as pequenas e rápidas de servir. Entrega, novas tentativas queued e status funcionam exatamente como na mídia — veja Entrega e novas tentativas; uma imagem de card que a Meta não consegue baixar falha na hora com 131052.

Mensagens de modelo

POST /api/v1/messages/send-template — somente WhatsApp, Pro obrigatório. Envia um modelo aprovado, a forma de iniciar uma conversa fora da janela de 24 horas (veja Capacidades). Variáveis, cabeçalhos de mídia e códigos de autenticação estão descritos em Modelos do WhatsApp → Enviando um modelo. A resposta e as regras de entrega são as mesmas de texto e mídia — veja abaixo.

Entrega e novas tentativas

Todos os endpoints de envio respondem 200 com success, message_id, status, error e error_code. Um 200 sozinho não significa que a mensagem saiu — leia status:

Uma requisição que o Fiwano recusa antes de chamar a Meta — text_too_long, invalid_recipient, um canal inativo, um limite de taxa — recebe um erro HTTP em vez de failed. Em send, send-media e send-interactive, uma mensagem failed também é informada ao dono do canal por e-mail.

No portal, a página Delivery problems de cada canal (aba Messages) lista as mensagens dos últimos 7 dias que estão queued aguardando nova tentativa (com o número da tentativa e o próximo horário) ou failed, com o código e o texto da Meta — o mesmo error que a API e o message.failed retornam. Inclui as mensagens do WhatsApp que a Meta aceitou e depois informou como falhas.

Um envio fica queued por um de dois motivos:

• A Meta falhou temporariamente (texto, mídia e interativas) — erro de rede, 5xx da Meta, rate limit ou um código de erro temporário. O Fiwano tenta de novo até 7 vezes ao longo de ~20 minutos. O dono do canal recebe um e-mail após 3 tentativas falhas e outro se todas falharem; você então recebe message.failed. send-template não repete: qualquer erro que a Meta retorne é failed, e você decide se e quando reenviar.
• A Meta respondeu devagar (qualquer envio) — veja abaixo.

Respostas lentas da Meta

Ocasionalmente a Meta leva mais de 30 segundos — às vezes mais de um minuto — para responder a um envio, na maioria das vezes enquanto baixa um arquivo grande. A chamada então retorna queued e o Fiwano espera a Meta confirmar a mensagem:

• Normalmente a confirmação chega e os webhooks habituais message.sent / message.delivered / message.read vêm em seguida.
• Se a Meta não confirmar nada em alguns minutos, o Fiwano envia uma mensagem de texto, mídia ou interativa mais uma vez (nunca um modelo). A primeira tentativa pode ter sido concluída afinal, então em casos raros o destinatário recebe a mensagem duas vezes — uma duplicata é preferível a uma mensagem perdida.
• Se nada for confirmado no fim, a mensagem passa a failed: você recebe message.failed e o dono do canal recebe um e-mail.

Não reenvie do seu lado enquanto uma mensagem estiver queued. Se o seu próprio cliente HTTP atingir o timeout antes da resposta, veja Tempo de resposta.