Símbolo da AmivuSímbolo da AmivuDevelopers

Canais e capacidades

O que cada conexão consegue fazer, e como perguntar antes de tentar.

A API é unificada; os canais não são. Um envia modelo aprovado, outro não; um confirma leitura, outro nem entrega. A matriz de capacidades é como você descobre isso sem tentar.

A matriz de capacidades

Esta tabela é gerada do código
Os valores abaixo saem da mesma função que a API usa para decidir se o canal aceita um tipo de mensagem. Ela não pode prometer o que o canal não faz — nem esconder o que ele faz.
RecursoWhatsApp oficialWhatsApp pareadoChat do siteInstagramMessengerE-mail
Texto✓✓✓———
Imagem✓✓————
Vídeo✓✓————
Áudio✓✓————
Documento✓✓————
Modelo aprovado✓—————
Botões——————
Localização——————
Recibo de entrega✓✓✓———
Recibo de leitura✓✓————
Janela de atendimento✓—————

Instagram, Messenger e e-mail aparecem com tudo em —: eles existem no modelo para que conectá-los depois não exija mudança de contrato, e hoje não têm adaptador de envio. A tabela diz isso em vez de prometer texto e falhar na primeira chamada.

O chat do site troca só texto, nos dois sentidos: o widget não envia anexo, e uma mídia mandada pelo painel não aparece para o visitante.

O que a API envia, por canal
Texto e mídia saem por POST /v1/messages onde a matriz diz que o canal os transporta — a mídia com um anexo subido antes em POST /v1/uploads (ver Anexos e mídia). Modelo aprovado é a exceção: mesmo marcado no WhatsApp oficial, ele ainda volta 422 unsupported_message_type pela API. Quando isso mudar, entra no changelog.

Como perguntar

Terminal
curl https://api.amivu.com.br/v1/channels \
  -H "Authorization: Bearer $AMIVU_API_KEY"

{
  "object": "channel",
  "id": "chn_01K7ZFA5X8Q2M4N6P8R0T2V4W6",
  "name": "WhatsApp Comercial",
  "type": "whatsapp",
  "provider": "meta",
  "status": "connected",
  "display_number": "+55 15 99110-5435",
  "capabilities": {
    "text": true,
    "image": true,
    "template": true,
    "buttons": false,
    "delivery_receipts": true,
    "read_receipts": true,
    "session_window": true
  }
}
Nunca esperamos que você adivinhe
Se o seu código precisa saber se pode mandar um modelo, leia capabilities.template — não deduza pelo type. É exatamente para isso que este campo existe.

WhatsApp são dois

O provider distingue duas conexões que se chamam “WhatsApp” e não são a mesma coisa:

  • meta — a Cloud API oficial. Tem modelo aprovado e a janela de 24 horas fora da qual só modelo passa.
  • whatsapp_web — uma sessão pareada por QR Code. Manda texto e mídia, não tem modelo e não tem janela.

Tratar os dois como iguais é o erro que mais custa aqui: um código que mande type: "template" sem olhar o provedor funciona num cliente e falha no vizinho.

status também importa. Um canal disconnected recusa envio com 422 channel_not_connected — e o caminho de volta é o painel, não uma retentativa.

Escrevemos sobre operação de atendimento, canais e IA no blog da Amivu.