Enviar mensagens

Duas ferramentas cobrem quase tudo: enviar_template (a qualquer hora) e enviar_mensagem (texto livre, dentro da janela de 24 horas).

A regra das 24 horas

É regra do WhatsApp, não nossa: texto livre só vai para quem escreveu para a empresa nas últimas 24 horas. Fora dessa janela, só template aprovado pela Meta. A API confere antes de enviar e responde 409 fora_da_janela_24h se não der.

Enviar um template

curl -X POST https://dev.onesendz.com/api/v1/enviar_template \
  -H "Authorization: Bearer $ONESENDZ_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "telefone": "+5511999990000",
    "template": "pedido_enviado",
    "variaveis": ["Marina", "#4521"],
    "chave_idempotencia": "pedido-4521-enviado"
  }'

• template: nome de um template aprovado. Veja os disponíveis com listar_templates (traz o texto e quantas variáveis cada um pede).
• variaveis: os valores de {{1}}, {{2}}... na ordem.
• numero_id: por qual número, se a empresa tiver mais de um.

Enviar texto livre

curl -X POST https://dev.onesendz.com/api/v1/enviar_mensagem \
  -H "Authorization: Bearer $ONESENDZ_API_KEY" -H "Content-Type: application/json" \
  -d '{"telefone": "+5511999990000", "texto": "Seu pedido saiu para entrega!", "chave_idempotencia": "pedido-4521-saiu"}'

Até 4.000 caracteres. Use quando o cliente acabou de escrever (por exemplo, respondendo a um mensagem.recebida).

Quem recebe

Identifique o contato de um destes jeitos:

• telefone: com DDD (de preferência com +55).
• contato_id: o id que a API devolveu.
• id_externo: o código do contato no seu sistema, se você salvou com salvar_contato passando id_externo.

Idempotência: enviar uma vez só

chave_idempotencia é obrigatória nos envios: um identificador único do envio no seu sistema (8 a 200 caracteres), como pedido-4521-enviado. Repetir o pedido com a mesma chave devolve o mesmo resultado e não envia de novo. Assim você pode reenviar com segurança depois de um timeout.

A resposta e o que acontece depois

{ "ok": true, "dados": { "enviado": true, "na_fila": true, "mensagem_id": "6906fb96-057e-46f5-a76c-78dabfcbaacf", "conversa_id": "70b5ccdd-..." } }

O envio entra na fila e sai em segundos. O resultado chega por webhook com o mesmo mensagem_id: mensagem.entregue, mensagem.lida ou mensagem.falhou (com o motivo e como resolver). Veja webhooks.

Cuidados que a API já tem por você

• Quem pediu para não receber marketing não recebe template de marketing.
• Tope da chave: passou do máximo definido, a chave para de enviar até o dia ou mês seguinte.