Visão geral de contatos

Um contato do Turbo Notify é um registro criado automaticamente a partir das mensagens trocadas entre um número da sua organização e outras pessoas. Não é um CRM. A agenda do WhatsApp não é sincronizada, e não há endpoints para criar ou excluir contatos manualmente.

Cada contato pertence a um número. Para o número principal, use as rotas sem alias (/v1/contacts, /v1/contacts/{id}, /v1/contacts/quota etc.) ou a forma com o alias main (/v1/numbers/main/contacts, /v1/numbers/main/contacts/{id} etc.). As duas são equivalentes. Para números extras, use /v1/numbers/{ref}/contacts. O mesmo telefone alcançado por dois números diferentes gera dois contatos distintos.

Conceito

Aspecto	Comportamento
Origem	Mensagens (`inbound` ou `outbound`), número próprio (`self`) ou menção em uma mensagem (`mention`)
Criação	Automática, na primeira vez que o par (número, telefone) aparece na sua organização
Identificador	`ct_{hex32}`: identificador público estável
Escopo	Por número: o mesmo telefone alcançado por dois números da mesma organização gera dois contatos distintos, com ids `ct_` diferentes (o mesmo vale para o mesmo telefone em organizações distintas)
Persistência	Sem expiração: o contato permanece enquanto a organização existir

Ciclo de vida

[Inbound] message.received ────────┐
                                   ▼
[Outbound] POST /v1/numbers/{ref}/messages ──► Contato criado ──► Enriquecimento (nome, foto)
                                   ▲                            ▼
[Self] number.connected ───────────┘                 Webhook: contact.created

Descoberta: na primeira vez que o par (número, telefone) aparece na sua organização, o contato é criado com o source correspondente.
Dados complementares: em seguida, o Turbo Notify preenche name e picture. Se essa etapa falhar, o contato existe do mesmo jeito, apenas sem esses dados.
Cota: cada contato distinto com quem você fala pelo Turbo Notify dentro do ciclo de faturamento atual (de cycle_start até cycle_end) ocupa uma vaga da cota, seja ele novo ou recorrente. A cota só volta a zero em resets_at.

Cota por plano

Plano	Contatos distintos/ciclo	Mensagens/ciclo
Gratuito	2	300
Lobo Solitário	100	1.800
Empresarial	5.000	50.000
Personalizado	50.000	500.000

As duas cotas são por número: cada número da organização tem a sua própria cota. O suporte pode ajustar a cota de uma organização, sempre por número, nunca como um teto único para a conta.

Origens (source)

inbound: primeira mensagem recebida desse telefone.
outbound: primeira mensagem enviada para esse telefone.
self: número da própria organização (principal ou extra). Vem com is_self=TRUE.
mention: telefone visto pela primeira vez ao ser mencionado em uma mensagem. Não houve troca de mensagens com ele: o contato existe apenas como referência e não ocupa a cota de contatos.

Fora de escopo

Não há POST /v1/numbers/{ref}/contacts: contatos surgem das mensagens.
Não há DELETE /v1/numbers/{ref}/contacts/{id}: contatos não são excluídos manualmente.
A agenda do WhatsApp não é sincronizada.