Enviar mensagens pela API: texto, mídia e modelos

Rotas

Passo a passo: enviar um texto

1. Tenha o id do ticket.
2. Chame a rota de envio:

curl -s -X POST https://http.pipebr.app/v1/conversations/b3a1c9de-0000-4000-8000-000000000100/messages \
  -H "Authorization: Bearer $PIPE_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"texto": "Seu pedido 1234 saiu para entrega."}'

1. A resposta é 201. A mensagem entra numa fila de entrega e nasce como pendente:

{
  "id": "b3a1c9de-0000-4000-8000-000000000200",
  "stateDelivery": "pendente",
  "insideOfWindow": true,
  "categoryCobranca": null,
  "content": "Seu pedido 1234 saiu para entrega.",
  "type": "texto",
  "warning": null
}

O estado muda depois para enviada, entregue, lida ou falhou, conforme o canal confirma. Acompanhe por webhook (evento mensagem.estado_entrega_alterado) ou lendo as mensagens do ticket.

Campos do corpo

Enviar um arquivo

1. Envie o arquivo cru no corpo, com o Content-Type dele. O parâmetro nome dá o nome do arquivo:

curl -s -X POST "https://http.pipebr.app/v1/attachments?nome=comprovante.pdf" \
  -H "Authorization: Bearer $PIPE_CHAVE" \
  -H "Content-Type: application/pdf" \
  --data-binary @comprovante.pdf

1. Guarde o id da resposta:

{
  "id": "b3a1c9de-0000-4000-8000-000000000300",
  "mime": "application/pdf",
  "bytes": 48213,
  "tipo": "documento",
  "link": "https://http.pipebr.app/v1/attachments/b3a1c9de-0000-4000-8000-000000000300?expires=0&signature=exemplo",
  "durationSec": null,
  "maxByMessage": 10
}

1. Envie a mensagem com o anexo e, se quiser, uma legenda:

curl -s -X POST https://http.pipebr.app/v1/conversations/b3a1c9de-0000-4000-8000-000000000100/messages \
  -H "Authorization: Bearer $PIPE_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"attachmentId": "b3a1c9de-0000-4000-8000-000000000300", "texto": "Segue o comprovante."}'

Para vários arquivos de uma vez, use POST .../messages/attachments com {"attachmentIds": ["...", "..."], "texto": "..."}. A resposta traz messages, uma por arquivo. Se um arquivo for recusado, nenhum é enviado.

Formatos aceitos no WhatsApp

Um áudio audio/webm com Opus é convertido para OGG no servidor e sai como nota de voz. O link do anexo vale por 15 minutos.

Enviar um modelo

Fora da janela de 24 horas, só modelos aprovados saem. Informe o template_id do canal do ticket e os valores das variáveis:

curl -s -X POST https://http.pipebr.app/v1/conversations/b3a1c9de-0000-4000-8000-000000000100/messages \
  -H "Authorization: Bearer $PIPE_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"template_id": "b3a1c9de-0000-4000-8000-000000000400", "parametros": ["Maria", "1234"]}'

Para listar os modelos do canal e ver status e variáveis, use Consultar cadastros. Modelo desativado dá 409 template_inativo; modelo não aprovado dá 409 template_nao_aprovado.

Localização e contato

{ "type": "localizacao", "localizacao": { "latitude": -23.55, "longitude": -46.63, "nome": "Loja Girassol" } }

{ "type": "contato", "contatos": [ { "nome": "Loja Girassol", "telefones": ["+5511955550000"] } ] }

Cartão de contato só funciona no WhatsApp. Cada cartão aceita de 1 a 5 telefones em formato internacional.

Reagir e reenviar

Reação com emoji (a empresa reage à mensagem do cliente). Envie null para remover:

curl -s -X POST https://http.pipebr.app/v1/conversations/b3a1c9de-0000-4000-8000-000000000100/messages/b3a1c9de-0000-4000-8000-000000000201/reaction \
  -H "Authorization: Bearer $PIPE_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"emoji": "👍"}'

A reação exige janela de 24 horas aberta, mensagem com menos de 30 dias e canal WhatsApp. Repetir o mesmo emoji não envia de novo (queued: false).

Para reenviar uma mensagem em estado falhou, chame POST .../messages/:messageId/resend. A resposta traz o id e o novo estado_entrega.

Ler as mensagens do ticket

GET /v1/conversations/:id/messages aceita limit, cursor, order_by=criada_em[desc], direction (entrada, saida ou interna) e estado_entrega (pendente, enviando, enviada, entregue, lida, reproduzida ou falhou). Cada item traz type, content, stateDelivery, errorCode, errorText (em português, para os códigos conhecidos da Meta), midia, respondeA, reacoes e encaminhada.