Disparar mensagens por automação

POST /automations/enrollments é como a API envia mensagens: você inscreve contatos numa automação já criada no painel, e ela dispara o template para cada um. Se ainda não leu, veja antes Como funciona o envio.

Antes de começar

1. Uma automação de disparo ativa no painel, com canal e template aprovado, da mesma conta do token. Automações básicas (manuais) não aceitam inscrição pela API.
2. O ID da automação — em GET /v1/automations ou na URL da automação no painel.
3. Créditos na conta (GET /v1/me → credits).

Contatos novos ou atualizados na hora

Mande os contatos em contacts. Cada item é criado ou atualizado como no create-or-update, e as propriedades enviadas já valem para as variáveis do template:

curl --request POST \
  --url https://api.picchat.com.br/automations/enrollments \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "automation_id": "0193e1b7-2a3c-7f40-9b51-6c7d8e9fa0b2",
    "contacts": [
      {
        "first_name": "Maria",
        "mobilephone": "5511999990000",
        "email": "maria.souza@example.com",
        "cupom": "BEMVINDA10"
      }
    ]
  }'

Um contato que já existe

{
  "automation_id": "0193e1b7-2a3c-7f40-9b51-6c7d8e9fa0b2",
  "contact_id": "0193f0a2-4b1c-7d3e-8f4a-5b6c7d8e9f01"
}

A resposta

{ "message": "Enrollment request sent to processing queue" }

O 201 só confirma que o pedido entrou na fila. A automação, o template, o contato e o saldo são conferidos logo depois, e um problema ali não volta para quem chamou. Confira o resultado em GET /v1/messages?automation_id=… ou nos totais de GET /v1/automations/{id}.

Variáveis do template

As variáveis do template ligadas a propriedades ({{etapa_do_funil}}, {{Nome da propriedade}}) são trocadas pelo valor da propriedade do contato. Propriedade sem valor sai como _ — garanta que os contatos têm os dados que o template usa.

Quando a mensagem sai

• Se o canal atende o tempo todo ou a automação ignora horário comercial, o envio é agendado para agora.
• Senão, vai para o próximo horário de atendimento do canal (até 7 dias à frente).
• Todos os contatos de uma mesma chamada recebem o mesmo horário.
• Sem créditos, a mensagem é registrada com erro Not enough credits e não sai.

Lotes

• Para muitos contatos, mande uma chamada com a lista em contacts — não uma chamada por contato.
• O tamanho máximo do lote depende do plano; acima dele a API responde 400 antes de enfileirar.
• Um item inválido (sem celular e sem e-mail, ou e-mail mal formado) descarta o lote inteiro. Valide os dados antes de enviar.

Não repita a chamada

Não há idempotência: chamar de novo com os mesmos contatos envia de novo. Guarde do seu lado o que já foi disparado e, em erro de rede, confira em GET /v1/messages antes de tentar outra vez.

Erros