Enviando Mensagens

O Fiwano tem três endpoints de envio — texto simples, mídia 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 Mensagens de modelo. 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"
  }'

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 — 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.

Envios de texto e de modelo não são afetados — 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. 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 de modelo

POST /api/v1/messages/send-template — somente WhatsApp, Pro obrigatório. Use um modelo pré-aprovado para iniciar uma conversa fora da janela de 24 horas (veja Capacidades). Apenas modelos APPROVED podem ser enviados — para criá-los e gerenciá-los, veja Modelos do WhatsApp.

Forneça os valores das variáveis por componente. Modelos posicionais ({{1}}, {{2}}) recebem arrays:

curl -X POST https://fiwano.com/api/v1/messages/send-template \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "channel_id": "a1b2c3d4e5f67890",
    "template_name": "order_confirmation",
    "language": "en_US",
    "recipient": "1234567890",
    "variables": {
      "header": ["Summer Sale"],
      "body": ["Pablo", "ORD-123", "25%"],
      "buttons": [{"index": 0, "value": "promo25"}]
    }
  }'

Modelos nomeados ({{customer_name}}) recebem objetos:

  -d '{
    "channel_id": "a1b2c3d4e5f67890",
    "template_name": "welcome_message",
    "language": "en_US",
    "recipient": "1234567890",
    "variables": {"body": {"customer_name": "Pablo", "order_number": "ORD-123"}}
  }'

Omita variables por completo se o modelo não tiver nenhuma.

Envios de modelo retornam o mesmo formato de resposta que envios de texto e mídia. O message_id é um UUID do Fiwano; guarde-o para correlacionar os webhooks de entrega:

{
  "success": true,
  "message_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "error": null,
  "error_code": null,
  "status": "sent"
}

Entrega e novas tentativas

Os três 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 e send-media, 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 e mídia) — 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 ou mídia 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.