Contacts overview

A Turbo Notify contact is a record created automatically from the messages exchanged between a number in your organization and other people. It is not a CRM. The WhatsApp address book is not synced, and there are no endpoints to create or delete contacts manually.

Each contact belongs to a number. For the main number, use the routes without an alias (/v1/contacts, /v1/contacts/{id}, /v1/contacts/quota, etc.) or the form with the main alias (/v1/numbers/main/contacts, /v1/numbers/main/contacts/{id}, etc.). Both are equivalent. For extra numbers, use /v1/numbers/{ref}/contacts. The same phone reached by two different numbers produces two distinct contacts.

Concept

Aspect	Behavior
Source	Messages (`inbound` or `outbound`), your own number (`self`) or a mention in a message (`mention`)
Creation	Automatic, the first time the (number, phone) pair shows up in your organization
Identifier	`ct_{hex32}`: stable public identifier
Scope	Per number: the same phone reached by two numbers in the same organization produces two distinct contacts, with different `ct_` ids (the same goes for the same phone in different organizations)
Persistence	No expiration: the contact stays as long as the organization exists

Lifecycle

[Inbound] message.received ────────┐
                                   ▼
[Outbound] POST /v1/numbers/{ref}/messages ──► Contact created ──► Enrichment (name, picture)
                                   ▲                            ▼
[Self] number.connected ───────────┘                 Webhook: contact.created

Discovery: the first time the (number, phone) pair shows up in your organization, the contact is created with the matching source.
Additional details: next, Turbo Notify fills in name and picture. If that step fails, the contact exists anyway, just without those details.
Quota: each distinct contact you talk to through Turbo Notify within the current billing cycle (from cycle_start to cycle_end) takes one slot of the quota, whether the contact is new or returning. The quota only goes back to zero at resets_at.

Quota per plan

Plan	Distinct contacts/cycle	Messages/cycle
Free	2	300
Lone Wolf	100	1,800
Business	5,000	50,000
Custom	50,000	500,000

Both quotas are per number: each number in the organization has its own allowance. Support can adjust an organization’s allowance, always per number, never as a single cap for the whole account.

Sources (source)

inbound: first message received from that phone.
outbound: first message sent to that phone.
self: a number of your own organization (main or extra). Comes with is_self=TRUE.
mention: phone first seen when it was mentioned in a message. No messages were exchanged with it: the contact exists only as a reference and does not take a slot of the contact quota.

Out of scope

There is no POST /v1/numbers/{ref}/contacts: contacts come from messages.
There is no DELETE /v1/numbers/{ref}/contacts/{id}: contacts are not deleted manually.
The WhatsApp address book is not synced.