Contacts
Consent
Record each contact’s consent on WhatsApp, email and SMS with its evidence, read it back, and let Trovacast enforce it on every send.
Consent is kept per contact and per channel — WhatsApp, email and SMS — and checked when a message is sent, not only when it is queued. You record the decisions your customers make on your own forms; the contact’s own acts (a STOP, an unsubscribe, a spam report) are recorded by Trovacast. Reading consent needs contacts:read; recording it needs consent:write. Consent belongs to the messaging product: without it these routes answer 403 ENTITLEMENT_MESSAGING_DISABLED.
- GET
/v1/contacts/{contactId}/consent/{channel}Retrieves a contact’s consent on one channel (marketing and updates) - PUT
/v1/contacts/{contactId}/consent/{channel}Records a contact’s consent decision on one channel - GET
/v1/contacts/{contactId}/consent/whatsappRetrieves a contact’s WhatsApp consent (marketing and updates) - PUT
/v1/contacts/{contactId}/consent/whatsappRecords a contact’s WhatsApp consent decision
/consent/{channel} takes whatsapp, email or sms. The dedicated /consent/whatsapp routes answer exactly as /consent/{channel} with whatsapp.
Two decisions per channel
| Decision | What it allows |
|---|---|
marketing | Full consent on the channel, marketing included: what a MARKETING WhatsApp template, a marketing email or a promotional SMS needs. |
updates | Consent to transactional messages only — order, delivery and cash-on-delivery messages: WhatsApp UTILITY and AUTHENTICATION templates and replies. A marketing opt-in admits updates too, unless updates is opted_out. |
Each is unknown, opted_in or opted_out, with where it came from (marketingSource, updatesSource): WEB_FORM, WRITTEN, VERBAL or OTHER for a decision you recorded, or the contact’s own act — INBOUND_MESSAGE, META_PREFERENCE, UNSUBSCRIBE_LINK, SPAM_COMPLAINT, …. A contact who writes to the business first is opted in to updates, never to marketing.
{
"object": "email_consent",
"contactId": "CONTACT_ID",
"marketing": "opted_out",
"marketingSource": "UNSUBSCRIBE_LINK",
"updates": "opted_out",
"updatesSource": "UNSUBSCRIBE_LINK",
"updatedAt": "2026-11-05T10:00:00.000Z"
}Record a decision
PUT /v1/contacts/{contactId}/consent/{channel} records a decision you collected — a checkbox on your checkout, a signed form, a recorded call.
curl -X PUT 'https://api.trovacast.com/v1/contacts/CONTACT_ID/consent/whatsapp' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: consent-checkout-1042' \
-H 'Content-Type: application/json' \
-d '{
"updates": "opted_in",
"source": "WEB_FORM",
"textShown": "Send me order updates on WhatsApp",
"capturedAt": "2026-11-05T09:30:00.000Z"
}'marketingandupdatesare eachopted_inoropted_out. Send either or both; a decision you leave out is unchanged.sourceis how the customer decided:WEB_FORM,WRITTEN,VERBALorOTHER.textShownis the consent text the customer saw — the checkbox label — up to 2,000 characters. It is required for an opt-in. It is stored encrypted as the evidence, with the key that recorded it, the source and the time.capturedAtis when the customer decided: it defaults to now and may not be in the future.- An
opted_outis never refused.
The contact’s own opt-outs
A STOP, an email unsubscribe or spam report, stopping marketing in WhatsApp itself, and WhatsApp refusing a marketing message because the contact stopped marketing are the contact’s own opt-outs. No decision you record can override one: an opt-in over it is 409 CONSENT_SELF_OPT_OUT. Only the contact can reopen it.
- On WhatsApp, a STOP keyword (
stop,stop all,unsubscribe,opt out,cancel,end,quit,revoke) counts only when the contact typed it as the whole message — “Opt-out!” counts, “please don’t stop” does not. Tapping a quick reply, button or list row is an answer to the business, whatever its label: a “Cancel” button cancels the order, never the consent. - An
opted_outyou record over the contact’s own opt-out keeps theirs and closes the other decision too: recording both decisionsopted_outfor a contact who stopped marketing in WhatsApp turns their updates off as well.
Coming back on WhatsApp
- START — a typed
start,unstop,subscribe,resubscribeoropt in(the same whole-message rule) restoresupdates, with the message as evidence, and is announced ascontact.consent.updatedwith sourcestart_keyword. It also lifts an updates opt-out you recorded earlier — never a later one. - Marketing stays stopped. START never touches
marketing. Only a marketing stop made in WhatsApp itself is lifted, by the contact resuming marketing there. - Any other message is a conversation, not a decision. After a STOP, “where is my order?” is delivered as
message.receivedbut reopens nothing. To answer, the contact needs to have sent START — or reach them on another channel. - Once the contact has reopened updates themselves, recording
updates: opted_inis accepted again.
What a send needs
| Channel | Rule |
|---|---|
A MARKETING template needs marketing: opted_in. UTILITY and AUTHENTICATION templates and replies go out with updates or marketing opted in, unless updates is opted_out. | |
Marketing email needs marketing: opted_in. Transactional email needs no opt-in, but is refused by updates: opted_out or the contact’s own unsubscribe or spam report. | |
| SMS | By the template’s DLT category: promotional needs marketing: opted_in; service_explicit needs marketing or updates opted in; service_implicit and transactional need nothing but are refused by an opt-out. |
A contact-level opt-out (doNotContact) and a blocked contact outrank every channel. A send refused by consent is a 409 naming the reason; calls follow the contact’s do-not-call and call opt-out state instead (see Calls).
Events
Every change on any channel — yours or the contact’s — is a contact.consent.updated event. To catch up after an outage, use the contacts reconciliation read, GET /v1/contacts?updatedAfter=.
| Event | When it is sent | Key scopes |
|---|---|---|
contact.consent.updated | A contact’s consent on a channel changed. WhatsApp, email or SMS consent moved — a STOP, an unsubscribe, a spam report, a reply, Meta’s own preference, or a write through the API or the console. consent.object names the channel.data: consent, livemode, source | contacts:read |
Errors
| Code | Status | Meaning and what to do |
|---|---|---|
CONSENT_MARKETING_REQUIRED | 409 | A marketing message to a contact who agreed to updates (transactional or utility messages) only: it needs marketing: opted_in on the channel. See Consent.What to do: Send a non-marketing message instead — a utility template, a transactional email, a service SMS — or record the contact's marketing opt-in once they give it (PUT /v1/contacts/{contactId}/consent/{channel}). |
CONSENT_OPTED_OUT | 409 | The contact opted out on this channel — or, for a marketing message, out of marketing — whether you recorded it or they did (STOP, an unsubscribe, a spam report).What to do: Do not retry. After a marketing opt-out a transactional or utility message may still go; only a new opt-in reopens the channel — theirs, if they opted out themselves. See What a send needs. |
CONSENT_REQUIRED | 409 | No opt-in on file for this kind of message on this channel.What to do: Record the contact's consent with PUT /v1/contacts/{contactId}/consent/{channel} once you have collected it (a WhatsApp or email refusal carries the contactId), then send again. See Record a decision. |
CONSENT_SELF_OPT_OUT | 409 | A consent write refused: it would override an opt-out the contact made themselves. An opted_out is never refused.What to do: Do not retry: only the contact can reopen it (on WhatsApp, a typed START restores updates). See The contact’s own opt-outs. |
CONTACT_BLOCKED | 409 | The contact is blocked, so nothing is sent to them.What to do: Do not retry: nothing reaches a blocked contact, on any channel. |
CONTACT_OPTED_OUT | 409 | On a send, the contact opted out of all contact or asked not to be contacted — it outranks every channel's consent. On a call, they opted out of calls themselves.What to do: Do not retry, and do not reach them another way. If the contact asks to hear from you again, a project member changes their state in the console. |