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. O valor text deve conter pelo menos um caractere que não seja espaço em branco; valores vazios ou somente com espaços são rejeitados com 422 antes de chamar a Meta. Espaços no início e no fim de um texto válido são preservados. Veja Capacidades.

O recipient tem os espaços ao redor removidos e é verificado antes de chamar a Meta: um valor vazio, um valor sem nenhum dígito (por exemplo um objeto serializado como [object Object]) ou um PSID/IGSID não numérico em um canal do Messenger/Instagram é rejeitado com 400 invalid_recipient (veja Erros). Nenhuma outra regra de formato é aplicada — um número de WhatsApp que a Meta consegue interpretar passa como está, e qualquer rejeição feita pela própria Meta continua voltando como status: "failed".

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 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. Falhas recuperáveis, incluindo 131053 de processamento/fetcher e 131056 de limite do par remetente-destinatário, retornam queued e usam o mesmo cronograma durável de novas tentativas que 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 retornam 200 com os mesmos campos success, message_id, error, error_code e 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 — o Fiwano está concluindo o envio em segundo plano e o message_id já é definitivo. Isso acontece após uma falha transitória da Meta (rede, 5xx, rate limit) — repetida até 7 vezes ao longo de ~20 min, com um e-mail de aviso antecipado após 3 tentativas falhas e um e-mail final se elas se esgotarem — e quando a Meta leva mais de 30 segundos para responder, o que ocasionalmente ocorre com mídias grandes — veja respostas lentas da Meta. Acompanhe o resultado pelos webhooks de status de entrega; não reenvie do seu lado.
• failed (success: false) — a requisição não será repetida. Para send e send-media, isso significa que a Meta rejeitou a mensagem de forma permanente (um destinatário que a Página ou o número não pode contatar, texto ou mídia acima do limite, payload malformado, janela de 24h fechada ou uma ação que a Meta nega para a conta — veja códigos de erro de envio), e o dono do canal é notificado por e-mail. Uma requisição que o próprio Fiwano recusa antes de chamar a Meta (text_too_long, invalid_recipient, recipient_equals_sender) responde com HTTP 400, não com failed. send-template não repete automaticamente, portanto qualquer erro de envio da Meta é retornado como failed; o cliente decide se e quando reenviar.

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