Collect future consent

This page explains how your agent collects opt-ins and handles opt-outs from now on, and what a contact texts, taps and gets back at each point. It also covers the JOIN link and QR code, the consent API, and the consent entries the app writes to the contact timeline. To record consent you already hold, use Add your existing consent.

Access

You do not need an RCS Studio account to review or change a system flow's messages, to see the JOIN link or to get an API key. You need one for Edit in RCS Studio, which also needs the Add, change and delete flows switch. Steps in the setup guide need Open and view the setup guide, and saving or using Fix needs Change the setup guide (save its settings). All three are on by default.

The JOIN Link tile needs only See links, on by default. The API Integration section, including the API key, needs the API consent switch, which is off by default, so only a HubSpot super admin can use it until a super admin turns it on. The Consent tab opens for anyone with See links, the manual consent switch or the API consent switch, and shows only what each allows. Manage your team in HubSpot lists every switch. The Chat with agent button needs a connected inbox, which only a HubSpot super admin can connect (Two-way inbox).

In Test Mode, a phone that has not accepted the tester invite never reaches the agent, so register your phone as a test device before you try a keyword or the JOIN link (Create and set up your agent).

How the system flows collect consent

When you create an agent, the app builds system flows that handle opt-in, opt-out and help. A flow is a set of messages chained together, so what a contact texts or taps decides what they get next. You review and reword them in the agent's setup guide, which Create and set up your agent explains how to open. The steps are Opt-In Capture, Opt-Out Capture and Help Capture, each opened from its tile on the agent's Overview tab.

System flowThe contactWhat it does
JOIN EntryTexts JOIN, START, SUBSCRIBE or OPTIN, or taps or scans the JOIN linkSends "Processing your opt-in request..." and passes the contact to Opt-In Confirmation. It records nothing itself
Opt-In ConfirmationIs passed on by JOIN Entry, Yes, Subscribe, a JOIN keyword or a JOIN during a live chatRecords the opt-in and sends the confirmation
Double Opt-In: {agent name}Is asked to confirmSends a prompt with Yes, Subscribe and No, Thanks, which pass the contact to Opt-In Confirmation or STOP Confirmation
STOP Opt-OutTexts a registered STOP keywordSends "Processing your opt-out request..." and passes the contact to STOP Confirmation. It records nothing itself
STOP ConfirmationIs passed on by STOP Opt-Out, No, Thanks, a typed opt-out or a STOP during a live chatRecords the opt-out and sends the opt-out confirmation
HELP ResponseTexts HELP or INFOSends your contact details
Unrecognized MessageTexts anything no keyword, button or link claimedCatches typed opt-outs, offers the consent prompt to opted-out contacts and contacts with no record, and replies to everyone else

From a contact's texts, only these flows record consent. The app does not infer consent from a message that no flow handled. Consent management explains where the result is stored.

The messages below are the defaults. On each step you can switch between Use template and Use custom text, then select Save. Edit in RCS Studio opens the message there if your account allows it.

Opt-in: JOIN Entry, Opt-In Confirmation and Double Opt-In

A new agent starts with JOIN on and double opt-in on. Opt-In Capture is where you review both and change the wording.

JOIN Entry

Turning on the JOIN flow creates the JOIN link and its QR code. The JOIN keywords are exactly JOIN, START, SUBSCRIBE and OPTIN. They are fixed: you cannot add, remove or rename one.

A contact who texts a JOIN keyword, or taps or scans the JOIN link, is opted in at once and gets the opt-in confirmation, even with double opt-in on. The keyword or the link is itself the consent action, so the contact is not asked a second time.

Opt-In Confirmation

The opt-in confirmation is the text a contact gets after they opt in. Choose a Message frequency, which fills the sentence "You're subscribed to receive {frequency} from {agent}". The options are Recurring messages (default), Occasional messages, Daily messages, Weekly messages, Bi-weekly messages, Monthly messages, Quarterly messages, Promotional messages, Transactional messages, Marketing messages, Alerts and notifications, or Other with your own wording. The default text is:

You're subscribed to receive recurring messages from {agent name}. Reply STOP to cancel. Reply HELP for help. Msg & data rates may apply.

Custom text must mention STOP and HELP, because carriers require it to tell contacts how to opt out and get help. The step warns you if either is missing. Include the message frequency and "Msg & data rates may apply." too. Save is disabled while Other is chosen with no frequency.

Double Opt-In

Double opt-in is an optional confirmation: the contact must answer a prompt before the opt-in counts. It needs the JOIN flow on. Otherwise the step says "Enable the JOIN flow above before enabling double opt-in." Use Disable to turn it off.

The prompt is sent in two cases:

  • Your system records consent through the consent API. The contact is not opted in until they tap Yes, Subscribe.
  • A contact who is opted out, or who has no consent record for the agent, texts anything that is not a keyword. See Unrecognized messages.

The default prompt is:

Would you like to receive RCS messages from {agent name}? Tap Yes to subscribe or No to decline.

For an agent whose use case is Marketing, the default is:

Would you like to receive marketing messages from {agent name}? Click Yes, Subscribe to agree to receive automated marketing msgs at this number. No purchase necessary.

A Not legal advice notice appears above it: "These messages are a starting point — not legal advice. Work with your legal team to ensure all consent disclosures meet regulatory requirements before launching." Marketing agents also see PEWC required for marketing programs: the message must state that autodialed messages will be sent to the number and that consent is not a condition of purchase, and your legal team must review and approve the copy.

The two button labels default to Yes, Subscribe and No, Thanks. Edit either under the preview, up to 25 characters. An empty label disables Save.

The contactThey receiveThe app records
Taps Yes, SubscribeThe opt-in confirmationAn opt-in, How "Double opt-in"
Taps No, ThanksThe STOP confirmationAn opt-out, How "Double opt-in declined"

Only the buttons count. A typed "yes" or "y" is handled like any other text, because RCS Studio does not read a typed reply to this message. Contacts can still text JOIN or STOP.

If you turn double opt-in off, the consent API opts the contact in directly, with no prompt. The prompt flow stays while the agent still uses it, so opted-out contacts and contacts with no record who text something that is not a keyword still get it. You cannot edit its text or buttons until you turn double opt-in back on.

What the app records for an opt-in

The app adds the agent to RCS Consent — Opted In on the contact that holds the number, creates a contact if none does, removes the agent from RCS Consent — Opted Out, adds the contact to the linked opt-in list if one is on, and writes a "Consent granted" timeline entry with How "JOIN flow" or "Double opt-in". A contact who is already opted in is not prompted again. On an agent that is not launched, an opt-in through the consent API, a single entry or a CSV import also registers the contact's number as a test device and sends the tester invite. A JOIN text or a double opt-in tap needs no invite, because the person is already talking to the agent.

Opt-out: STOP Opt-Out and STOP Confirmation

Carriers require every messaging program to honor an opt-out. A new agent already has the STOP flow that does it. In the STOP opt-out flow sub-step of Opt-Out Capture, confirm the toggle is on, which creates the flow and registers the keywords. Then edit the STOP confirmation message or keep the default:

You've been unsubscribed from {agent name}. You won't receive any further messages.

An empty text restores the default.

Which words opt a contact out

Twenty keywords are registered on the STOP Opt-Out flow, and the app keeps the list fixed. They work in every case:

STOP, OPTOUT, UNSUBSCRIBE, END, QUIT, CANCEL, REMOVE, STOPALL, REVOKE, PARA, PARE, CANCELA, FIN, TERMINAR, SALIR, ARRET, CEASE, DESIST, STOP2END, STOP2QUIT

Any other text reaches the Unrecognized Message flow, which first checks it against a wider list of more than 100 opt-out words and phrases, such as OPT OUT, STOP2CANCEL, STOP TEXTING ME, PLEASE STOP, TAKE ME OFF THE LIST, DON'T TEXT ME and WRONG NUMBER. The wider list is also checked during a live chat.

Matching rules for every keyword:

  • A keyword matches the whole message, ignoring capitals, punctuation and accents. join, Join! and JOIN are the same. "I want to join" and "I think I want to stop" are not keywords.
  • A message with a question mark is never treated as consent.
  • Words such as no, nope, nah, no thanks, block, decline and not interested are ordinary answers, not opt-outs.

A contact who taps Block in their messaging app is opted out too, with the source "Blocked in messaging app". They get no reply, and unblocking does not undo it.

What the app records for an opt-out

When a STOP keyword arrives, the app sets RCS Consent — Opted Out for this agent on every contact that holds the number in Phone or Mobile phone. It then removes the contact from the opt-in list if one is linked and on, closes any open inbox thread with this agent, and writes a "Consent revoked" timeline entry, only when the contact actually had the opt-in. If no contact has the number, the app creates one that holds only the phone number and the opt-out, so a later import or API opt-in can see the person asked to stop. This happens for STOP and No, Thanks, but not for an opt-out through the API, an admin removal, a CSV import or Block. A number that is not valid is ignored. Consent management explains what an opt-out means for workflows, and Two-way inbox explains what it does to a thread.

HELP Response

The Help Capture step sets the reply a contact gets when they text HELP or INFO, which carriers require, and the buttons under it. A new agent already has a HELP reply with a placeholder support email. Replace it with your real contact details. The app answers HELP whether or not the contact has opted in, because carriers require it.

The default text is "Here's how to reach us. Tap an option below." once a button exists, and "Here's how to reach us." until then.

Add buttons under Contact buttons, with labels up to 25 characters.

ButtonNeedsDefault label
+ WebsiteA URL starting with http:// or https://. You can also choose how it opens (browser or a webview in the messaging app)Visit Website
+ PhoneA complete international phone numberCall Support
+ Chat with agentA connected inbox. Without one the button is disabled, and Connect an inbox first opens the Inbox stepChat with agent

RCS has no email button, so the app adds the support email to the end of the message text as "Email us at {email}." With Use custom text the sentence is part of the text, so edit or delete it there.

If the reply would offer no way to reach you (no website, phone, real email, or enabled Chat with agent with an inbox), the app adds the placeholder [email protected]. The health check flags it: "Your HELP reply still shows the placeholder support email", or "Your HELP reply has no contact details" when there are none. Add your real details and save.

Chat with agent also needs support hours, which default to Mon-Fri, 9 AM to 5 PM, CT. The chat messages, and the opt-in prompt a contact gets when they tap it without having opted in, are in Two-way inbox.

Unrecognized messages

RCS Studio sends any text that is not a keyword to the agent's default state, the catch-all reply for any text no flow claims. The app builds that state as the Unrecognized Message flow. There is nothing to switch on: the app creates the state with the agent and rewrites it on Fix, which needs the two setup guide switches.

Each text that no keyword, button or link claimed goes through the app's keyword check and a consent lookup, then through these routes. RCS Studio takes the first that matches.

  1. The keyword check gave no answer. The contact gets: "We couldn't process your request right now. If you want to stop receiving messages, please reply STOP again in a few minutes."
  2. The text is an opt-out. The contact gets the STOP confirmation and the app records the opt-out, exactly as if they had texted STOP. A sentence containing "stop" is not an opt-out.
  3. The contact is opted out, or has no consent record for this agent. The contact gets the Double Opt-In prompt, and tapping Yes, Subscribe records an opt-in. This is how an opted-out contact opts back in.
  4. Everyone else (an opted-in contact, or a consent lookup that failed) gets the HELP reply when an inbox is connected or when HELP has a real contact detail, a website, phone number or email. The placeholder [email protected] does not count. Otherwise they get "Sorry, we didn't understand that. Reply HELP for help or STOP to opt out."

The app makes the route 4 choice when it writes the state, so saving Help Capture with a real contact detail switches the "didn't understand" reply to the HELP reply.

If the consent lookup cannot answer, the app treats the contact as opted in and uses route 4, so a failure never sends the prompt. A failed keyword check sends route 1 instead, so a STOP is never silently lost, and a plain STOP from the fixed list is still honored.

During a live chat

If you have connected an inbox, the app checks every text in an open chat first. An opt-out gets the STOP confirmation and closes the chat in the inbox. A JOIN keyword gets the opt-in confirmation and leaves your team's thread open. If the chat has ended, the text follows routes 1 to 4. If the app could not answer either check, the contact gets "Sorry, I can't respond right now. Please try again in a few minutes. To stop messages, reply STOP again." The next text is checked again, and if it keeps happening, open the Inbox tile and select Fix. Retiring the agent also releases a live chat. Any other text goes to your team in the inbox.

A default state you built yourself

An agent created in RCS Studio can already have its own default state. With no inbox connected, the app never replaces it, so typed opt-outs such as OPT OUT are caught only if your state catches them. The 20 STOP keywords still work. The Opt-Out Capture tile shows Needs fixing, which Fix cannot clear. Connecting an inbox replaces your state with Unrecognized Message, so re-add your own routing in RCS Studio afterwards if you need it.

The JOIN link and QR code

The JOIN link is a short web address and QR code that opts a contact in when they tap or scan it. Share it in your app, on your website or in a storefront. It sits in the JOIN Link tile on the agent's Consent tab. The app creates it with the JOIN flow, not on the Links tab. Until the JOIN flow is on, the tile shows "No JOIN link configured": "Enable the JOIN flow in the setup guide to get a shareable link and QR code." Without setup access it says "There is no JOIN link yet."

The tile shows the QR code and the link, in the form https://link.rcsstudio.ai/ followed by an 8-character code. Copy link copies the address, and Download PNG and Download SVG save the QR code for print or a web page.

Tapping or scanning the link opens the JOIN Entry flow and records the contact as opted in, even with double opt-in on.

The code is kept if the link is deleted in RCS Studio or recreated, so printed QR codes keep working. If the code is taken, a new one is generated. On the Links tab the app refuses to change or delete the JOIN link. Uninstall RCS Studio says what happens to it when you uninstall.

In Test Mode, a JOIN text or scan from a phone that has not accepted the tester invite never reaches the agent, so add the number as a test device first.

The consent API

Use the consent API to record an opt-in or opt-out from your own server, for example when a customer ticks a box on your checkout page. Each agent has its own endpoint and API key, on the agent's Consent tab under API Integration. Record only consent you actually hold, because the API does not check where it came from.

Turn on the agent's JOIN flow first. Until it is on, the tab shows "Setup required" and no endpoint. The tab also shows Double Opt-In: Enabled or Disabled, which you change in the setup guide.

Get an API key

  1. On the agent's Consent tab, find API Integration.
  2. Select Generate / Rotate API Key.
  3. Confirm with Generate new key (if a key exists, the window asks "Replace the current API key?"), then copy the key. "Copy this key now — it won't be shown again."

The key is 64 hexadecimal characters. The app stores only a hash of the key, so it cannot be shown again. If the agent already has a key, a new one stops the old one working immediately: "Every website, form or system that uses it will be rejected until you give it the new key."

Send a request

The API accepts browser requests only from HubSpot and this app's own pages, so call it from your server and keep the key out of web pages and apps.

The Consent endpoint field shows your agent's URL. Copy cURL copies a complete example:

curl -X POST 'https://…/hubspot/consent?agentId=YOUR_AGENT_ID' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{"action":"opt_in","phone":"+15551234567"}'

The server rejects numbers with a 555 area code, so replace the example number. +12125551234 is accepted.

FieldWhat to send
x-api-key headerThe agent's API key
agentIdIn the query string (or the body)
actionopt_in or opt_out
phoneA valid number: E.164, 10-digit US, or 11 digits starting with 1
email or contactIdInstead of phone: the app looks up the contact's phone number

The older field names msisdn, optIn and optOut still work, but use the names above. There is no idempotency key, but repeating an opt-in is safe: it returns already_opted_in and writes no second timeline entry.

The API does not check whether the contact has opted out. An opt_in for a number that replied STOP records the opt-in, and the contact is messageable again. With double opt-in on, the prompt is sent to opted-out contacts too. Record Existing Consent and CSV import skip opted-out contacts by default, but the API does not. You are responsible for not re-subscribing people who opted out, so check the contact's consent in HubSpot first.

Responses

With double opt-in off, an opt-in records consent at once and sends no message. With double opt-in on, it records nothing yet. A successful call returns 200.

ResponseMeaning
{"success":true,"status":"opted_in"}Consent recorded (double opt-in off)
status already_opted_inThe contact was already opted in. No prompt is sent
{"accepted":true,"status":"pending_confirmation"}Double opt-in on: the prompt was sent on a best-effort basis, and the response is the same if the send fails. Consent is recorded when the contact confirms
status opted_out or not_opted_inOpt-out result. not_opted_in means the number was not opted in to this agent, or no contact holds it
propertyWriteFailed: trueThe HubSpot consent property write failed. Check the contact
error test_device_failedThe tester invite could not be created, the agent is not deployed (agent_not_deployed), or its test device limit is reached (device_limit_reached). Nothing is recorded. The body carries reason and message

Errors: 400 for invalid_body, missing_fields, invalid_phone, missing_identifier (no phone, email or contactId), cannot_resolve_phone (the contact has no phone number, or the email matches no contact) and invalid_action. 401 unauthorized means a missing or wrong key, or an agent that is not on this installation. 503 portal_disconnected means the HubSpot connection is not active. 503 consent_write_failed and 500 service_error are failures to retry.

The API stage allows 50 requests a second with bursts of 100, shared by all callers. Generating a key is limited to 2 a second.

The API in Test Mode

With double opt-in off, the API records the opt-in immediately, registers the number as a test device if needed, and adds testerInvite (sent, pending or registered) to the response. With double opt-in on, it returns accepted:false with tester_invite_sent or tester_invite_pending and records nothing. Once the contact has accepted the invite, send the same call again.

Consent entries on the contact timeline

Every consent change adds an RCS Consent Event to the contact's activity timeline. They appear in the Activity tab of the contact record and show Consent granted or Consent revoked, the agent's name and How consent changed. No feature switch controls these entries.

HowWhat happened
JOIN flowThe contact texted JOIN or used the JOIN link and was opted in directly
Double opt-inThe contact tapped Yes, Subscribe
Double opt-in declinedThe contact tapped No, Thanks
STOP flowThe contact texted a STOP keyword
Blocked in messaging appThe contact tapped Block
APIYour system called the consent API
Manual entry, CSV import, Admin opt-out, Admin removal and RCS Studio flowYou or a system recorded it. Manual entry (re-opt-in override) and CSV import (re-opt-in override) mark opting in a contact who had opted out
Edited in HubSpotSomeone changed the consent properties. Edited in HubSpot (re-opt-in of an opted-out contact) marks an edit that opted in a contact who had opted out

The app writes an entry only when the agent moves in or out of RCS Consent — Opted In, so repeating an opt-in, or opting out a contact who never opted in, writes none. Consent management explains what the app does when someone edits the properties. The sent, received, failed and expired message entries are covered in Send RCS messages from workflows.

When the app cannot answer

If the app does not respond in time, nothing is recorded. A STOP keyword or No, Thanks that could not be recorded gets "We couldn't process your request right now. Please reply STOP again in a few minutes." A failed JOIN or Yes, Subscribe gets "Please reply JOIN again in a few minutes." instead. Messages your contacts and team may see lists every fixed message, and Uninstall RCS Studio says what an agent does after you uninstall.

Troubleshooting

SymptomCauseFix
A contact texted STOP or OPT OUT and the property did not changeThe STOP flow is off or broken, or the agent has its own default stateOn the Opt-Out Capture tile select Fix. For your own state, add the opt-out routing there
A contact typed "yes" and nothing happenedTyped replies to the prompt are ignoredThey tap Yes, Subscribe
A contact got "Sorry, we didn't understand that", or gets no HELP replyNo inbox and no real HELP contact detail, or HELP is not set up ("Your HELP reply is not set up" or "is missing")Set it up in Help Capture and save. Until HELP is set up, a HELP text is handled as an unrecognized message
401 unauthorizedOld key after a rotation, or wrong agentUse the current key for that agent
A browser form fails, or no JOIN Link tile showsThe API refuses browser origins, or you lack See links (JOIN link) or the API consent switch (API integration)Call the API from your server, or ask a super admin

The health rows behind each tile are listed in Create and set up your agent.

Next


Did this page help you?