Endpoint
write:contacts
Corpo da requisição
Encontrar antes de criar
Antes de gravar, a API procura um contato da organização com as mesmas chaves, nesta ordem:external_id, telefone (em qualquer grafia — +5514999990000, 5514999990000, 14999990000, (14) 99999-0000 casam o mesmo contato) e e-mail.
Com external_id no corpo, a criação é idempotente: se o contato já existir, a resposta é HTTP 200 com o registro existente e meta.matched_by dizendo por qual chave casou. Reenviar a mesma requisição (retry de rede, reentrega de fila) devolve sempre o mesmo id, sem criar duplicata. O contato existente não é alterado — para complementar dados, use Atualizar contato.
Sem
external_id, telefone ou e-mail já cadastrados devolvem HTTP 409, com o ID do existente no corpo:
GET /v1/contacts?phone=..., ?email=... ou ?external_id=... — veja Listar contatos.
O contato criado por aqui não entra em nenhuma conversa nem negócio automaticamente. Ele nasce com a identidade de WhatsApp derivada do telefone (
whatsapp_jid), pronto para receber uma mensagem por Enviar mensagem. Quem decide se vira oportunidade é o seu processo comercial, depois.Marketing
marketing_consent registra a autorização que você coletou fora da SocialSell — por exemplo, o aceite no formulário do seu site:
marketing_opt_out registra o descadastro, com origem api:
O descadastro vence a autorização: um contato descadastrado fica fora de todo envio promocional, mesmo autorizado. Cada mudança entra no histórico do contato. O resultado aparece no bloco
marketing da resposta — veja Objeto contato.
Quando o contato já existe e a resposta é 200, marketing_consent e marketing_opt_out não são gravados, como o resto do corpo. Para registrar no existente, use Atualizar contato.
Exemplo de requisição
Exemplo de resposta
HTTP 201 quando criou; HTTP 200, com o mesmo corpo, quando já existia e o corpo trazia external_id.
contact.created em webhooks configurados. Quando a resposta é 200 (contato já existia), nenhum evento é disparado.
Você informa apenas
phone. A SocialSell resolve e mantém internamente a identidade necessária para enviar pelo WhatsApp. O campo whatsapp_jid é somente leitura e não deve ser enviado na criação.