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. Veja Capacidades.

Mensagens de mídia

POST /api/v1/messages/send-media — licença Pro obrigatória. A Meta busca o arquivo diretamente de media_url; o Fiwano nunca o baixa nem o armazena. Passe media_type (image, audio, video, document) 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 ≥ 5 min. Uma URL pública é acessível por qualquer um que a descubra.

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=600",
    "caption": "Your order photo"
  }'

Sempre verifique success. Em caso de falha, a resposta inclui um error_code da Meta — por exemplo 131052 (a Meta não conseguiu baixar a URL) ou 131053 (formato/tamanho não suportado, ou a Meta aplicou rate limit à rede do seu host — tente um grande provedor de nuvem). Os limites de tamanho de arquivo e a tabela completa de error codes estão em Capacidades e na Referência da API.

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.

Entrega e novas tentativas

send e send-media retornam 200 com um campo status, porque o que acontece depois que a Meta aceita a requisição importa:

• sent — a Meta aceitou. Acompanhe o resto pelos webhooks de status de entrega (message.delivered / read / failed) — veja Recebendo Mensagens.
• queued — uma falha transitória da Meta (rede, 5xx, rate limit). O Fiwano tenta novamente em segundo plano (até 7 vezes ao longo de ~20 min). Você recebe um e-mail de aviso antecipado após 3 tentativas falhas e um e-mail final se elas se esgotarem.
• failed (success: false) — um erro permanente (destinatário inválido, texto acima do limite, payload malformado). Não é retentado — corrija a requisição e reenvie. O dono do canal é notificado por e-mail.

Portanto 200 por si só não significa "entregue" — sempre leia success e status.