PicChat

Automações

Inscrever contatos em uma automação

POSThttps://api.picchat.com.br/automations/enrollments

É assim que a API envia mensagens: você inscreve contatos numa automação ativa (criada no painel com canal e modelo) e ela dispara o modelo para cada um. A resposta 201 só confirma que o pedido entrou na fila; a validação de negócio (automação existe na conta, não é básica, modelo existe, contato existe, saldo) acontece depois e não volta para quem chamou. Confira o resultado em GET /v1/messages?automation_id=... Com contacts, cada item é criado ou atualizado como no create-or-update (inclusive propriedades enviadas como chaves extras, que já valem para as variáveis); um item inválido (sem celular/e-mail ou com e-mail mal formado) descarta o lote inteiro. Com contact_id, usa um contato existente da conta. As variáveis {{internal_name}} (ou {{Nome da propriedade}}) do modelo são trocadas pelo valor da propriedade do contato; sem valor saem como "", e propriedades de seleção ainda saem como "". Horário: se o canal atende o tempo todo ou a automação ignora horário comercial, o envio é agendado para agora; senão, para o próximo horário de atendimento do canal (até 7 dias à frente). Todos os contatos da chamada recebem o mesmo horário; o intervalo da automação não é aplicado nesta etapa. Sem saldo, a mensagem é registrada com erro "Not enough credits" e não sai. Não há idempotência: cada chamada gera um ex_id3 próprio e repetir a chamada repete o envio. O corpo é estrito (campos extras, inclusive account_id, dão 400); o escopo vem do token.

Autenticação: Bearer tokenPermissão: Token da conta (Bearer). Estas rotas não passam pelo grupo de permissão do usuário.

Corpo da requisição (JSON)

Campos do corpo

  • automation_idstring (uuid)obrigatório

    ID (UUID v7) da automação ativa que fará o envio. Obrigatório na prática.

  • contactsarray<ContatoCriarOuAtualizar>

    Contatos a inscrever, criados ou atualizados na hora. Cada item segue as mesmas regras de POST /contacts/create-or-update (mobilephone ou email obrigatório; chaves extras viram propriedades). Aqui números em campos de texto são aceitos e convertidos. Limitado ao lote de disparo do plano.

  • contacts[].first_namestring

    Nome. Em contato existente, vazio ou ausente mantém o valor atual.

  • contacts[].last_namestring

    Sobrenome. Em contato existente, vazio ou ausente mantém o valor atual.

  • contacts[].mobilephonestring

    Celular (texto, não número). A API remove tudo que não é dígito: até 11 dígitos sem começar por 55 recebe o DDI 55; começando por 55 com até 13 dígitos fica como está; mais de 13 dígitos é tratado como ID de grupo (`is_group` = true); qualquer outro formato é descartado. Só números brasileiros são normalizados corretamente.

  • contacts[].emailstring (email)

    E-mail. É gravado em minúsculas e sem espaços; formato inválido derruba a requisição (500).

  • contacts[].statusstring

    Status livre do contato. Enviado sempre sobrescreve.

  • contacts[].is_marketingboolean

    Aceita comunicação de marketing.

  • contacts[].fontstring

    Origem do contato. Valor fora da lista derruba a requisição com 500.

    referralsorganic_searchofflinesocial_mediapaid_searchpaid_socialemail_marketingother_campaignsdirect_trafficdirect_insertionimportation

  • contacts[].font_detailstring

    Detalhe livre da origem (ex.: "formulario-site").

  • contacts[].isGroupboolean

    Marca o contato como grupo. Só vale na criação; números com mais de 13 dígitos já viram grupo automaticamente.

  • contacts[].numberValidboolean

    Marcação manual de número validado.

  • contacts[].emailValidboolean

    Marcação manual de e-mail validado.

  • contact_idstring (uuid)

    ID (UUID v7) de um contato que já existe na conta. Se vier junto com `contacts`, tem prioridade e `contacts` é ignorado.

  • user_idstring (uuid)

    ID (UUID v7) de um usuário da sua conta. Só serve para automações com destino "usuário" (aviso interno para a equipe); obrigatório quando não há `contacts` nem `contact_id`.

Respostas

201Pedido aceito e enfileirado. Não garante o envio.

  • messagestringobrigatório

    Sempre "Enrollment request sent to processing queue".

400Corpo com campo não permitido, ou mais contatos que o lote de disparo do plano.

403Automação desativada, ou `account_id` diferente da conta do token.

422Falha de validação do corpo (class-validator). `message` é uma lista; `errorCode` aparece quando o primeiro item tem código catalogado.

498Token ausente, inválido, de conta inexistente ou revogado. Status não padrão (498), usado em toda a API.