Trovacast

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.

/consent/{channel} takes whatsapp, email or sms. The dedicated /consent/whatsapp routes answer exactly as /consent/{channel} with whatsapp.

Two decisions per channel

DecisionWhat it allows
marketingFull consent on the channel, marketing included: what a MARKETING WhatsApp template, a marketing email or a promotional SMS needs.
updatesConsent 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.

Email consent after an unsubscribe (json)
{
  "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.

Record a WhatsApp opt-in
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"
}'
  • marketing and updates are each opted_in or opted_out. Send either or both; a decision you leave out is unchanged.
  • source is how the customer decided: WEB_FORM, WRITTEN, VERBAL or OTHER.
  • textShown is 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.
  • capturedAt is when the customer decided: it defaults to now and may not be in the future.
  • An opted_out is 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_out you record over the contact’s own opt-out keeps theirs and closes the other decision too: recording both decisions opted_out for a contact who stopped marketing in WhatsApp turns their updates off as well.

Coming back on WhatsApp

  • START — a typed start, unstop, subscribe, resubscribe or opt in (the same whole-message rule) restores updates, with the message as evidence, and is announced as contact.consent.updated with source start_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.received but 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_in is accepted again.

What a send needs

ChannelRule
WhatsAppA 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.
EmailMarketing 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.
SMSBy 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=.

EventWhen it is sentKey scopes

Errors

CodeStatusMeaning and what to do
CONTACT_BLOCKED409The 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_OUT409On 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.