Send RCS messages from workflows
The Send RCS Message action adds RCS Studio to HubSpot's workflow builder. When a contact reaches it, the app sends the flow you chose, from the agent you chose, to the contact's phone number. This page covers how to build a workflow with the action, what its checks and results mean, how to handle contacts who have not opted in, and what the app writes to the contact timeline.
Access
You do not need an RCS Studio account to add or run the action. HubSpot calls the app with a signed request, and the app does not check who built the workflow. No switch on the Settings page controls the action. Adding actions to workflows is a HubSpot permission, and custom actions need a HubSpot plan with Professional or Enterprise workflows. RCS Studio must still be connected to the portal. If it is not, every run fails with "Installation not configured".
Where are you starting from?
The action works on contacts in a contact-based workflow, not on companies, deals or other objects. Find your case, then follow Build a workflow.
| If you are here | Do this first |
|---|---|
| You have no agent yet, or its setup guide steps are not done | Create and set up your agent |
| You have no flow to send | Build one in RCS Studio. The action sends an RCS Studio flow (Flows, links and connectors). |
| Your contacts have not opted in | Consent management. The action sends only to a contact who has opted in to that agent. |
| Your contacts have no phone number in the property the app uses | Add one. The property is Phone Number by default, or Mobile Phone Number if your portal is set to it (Manage your team in HubSpot). |
| Your agent is still in Test Mode | Register the recipient phones as test devices. An agent in Test Mode reaches only devices that accepted the tester invite, so a send to anyone else can look successful and never arrive (Create and set up your agent). |
When a contact reaches the action, it runs a series of checks on the agent, the flow, the phone number and the contact's consent. If every check passes, it sends the flow. If one fails, it skips the contact and the workflow continues with the next step. The action sets Send Status, Not Sent Reason and Message ID for the steps that follow.
Build a workflow
Step 1: Create the workflow and enroll only opted-in contacts
- In HubSpot, go to Automation > Workflows and create a contact-based workflow, or open one.
- Set the enrollment trigger. Add the filter RCS Consent — Opted In is any of your agent. This is the contact property the app sets when a contact opts in. Contacts without consent then never enter the workflow.
The action checks the contact's consent itself, so a contact enrolled without it is skipped. See Contacts who have not opted in.
Step 2: Add the action
- Select + to add an action and search for RCS Studio.
- Select Send RCS Message.
Step 3: Choose the agent and flow
| Field | What to enter |
|---|---|
| RCS Agent | The agent to send from. An agent that is not set up shows (setup needed) after its name |
| RCS Flow | The flow to send. A flow can be a single message, so to send one message, pick a flow that has only one. The list fills in after you pick an agent. For an agent whose setup is not finished it shows only Finish this agent's setup first |
| Template Parameters | Read-only. Lists the parameters the selected flow declares, each marked (required) or (optional), or says No parameters defined for this template. You cannot type here |
| Set Parameters | Values for those parameters, in the format key=value, one per line |
Both lists support search. The flow list offers the flows you can start a conversation with. The app's own opt-out, opt-in and help flows are never offered.
Step 4: Pass values with Set Parameters
Use Template Parameters to see which keys the flow expects, then add a matching key=value line for each in Set Parameters. The app does not fill in any values for you, such as first name or phone number. A value reaches the flow only if you write a line for it.
HubSpot's token picker can insert contact and company data. HubSpot resolves the tokens before the request reaches the app:
firstname={{ Contact: First Name }}
company={{ Company: Name }}
offer_code=SUMMER25
- Up to 20 parameters per action. Lines after the twentieth are ignored.
- A key uses letters, numbers, underscores or hyphens, up to 64 characters.
- A value is cut off at 1,024 characters.
- A line that is blank, has no
=, has an empty key or has an invalid key is dropped without any message. - Required parameters are not enforced. If you leave one out, the app still sends.
Step 5: Use the results and turn the workflow on
The action gives later steps these outputs, which you can branch on or add to a message:
| Output | Meaning |
|---|---|
| Send Status | SUCCESS, FAILED, SKIPPED_OPTED_OUT, SKIPPED_NO_CONSENT or SKIPPED_CONSENT_UNVERIFIED |
| Not Sent Reason | Text that says why a contact was skipped or failed. Empty after a successful run |
| Message ID | The id of the sent message |
Save the action and turn the workflow on. Contacts who meet the trigger now receive the flow.
A contact's reply reaches your HubSpot inbox only when the contact taps Chat with agent in your HELP reply. See Two-way inbox.
Guards, skips and failures
The action checks every contact before it sends, in the order below, and stops at the first check that fails.
- The workflow always continues. A skipped or failed contact moves on to the next step. Use Send Status in a later branch to act on it.
- The reason is in the history. The action's history entry and its Not Sent Reason output show the text in the table. A successful run fills Message ID and leaves Not Sent Reason empty.
- Skips and failed runs write nothing to the contact timeline. See What the app writes to the contact timeline.
| # | Check | Send Status | Not Sent Reason shows | Fix |
|---|---|---|---|---|
| 1 | No agent selected, or a placeholder row | FAILED | Missing agentId — select an RCS agent in the workflow action configuration | Open the action and choose a real agent in RCS Agent |
| 2 | No flow selected | FAILED | Missing message template — select a template in the workflow action configuration | Choose a flow in RCS Flow after choosing the agent |
| 3 | A system flow | FAILED | This message template is managed by the HubSpot integration and cannot be sent from a workflow. Choose another template. | Choose one of your own flows. System flows never appear in the picker, so this happens only after a flow's role changed or for a stale or older workflow |
| 4 | The app is not connected for this portal | FAILED | Installation not configured | Reconnect RCS Studio. See Install RCS Studio for HubSpot |
| 5 | The contact's data could not be read | SKIPPED_CONSENT_UNVERIFIED | Not sent: this contact's consent could not be verified because HubSpot was unavailable. The send was not retried. | Nothing is sent and the run is not retried. Re-enroll the contact. This can happen briefly after the action is edited |
| 6 | The contact has no number in the phone field in use | FAILED | Contact has no Phone Number, or Contact has no Mobile Phone Number, depending on the field in use | Fill in that property on the contact. A super admin sets which field the app uses in Settings |
| 7 | The phone number is not valid | FAILED | Contact phone number is invalid or missing country code | Store the number with its country code. A number with no country code is read as a US number |
| 8 | The contact opted out | SKIPPED_OPTED_OUT | Not sent: this contact has opted out of messages from this RCS agent. | Nothing: do not message them. They can opt back in |
| 9 | The contact has no opt-in | SKIPPED_NO_CONSENT | Not sent: this contact has no recorded opt-in for this RCS agent (the agent is not in the contact's RCS Consent — Opted In property). | Get consent first. See Contacts who have not opted in |
| 10 | The contact's conversation record holds an opt-out | SKIPPED_OPTED_OUT | Not sent: this contact has opted out of messages from this RCS agent. | As check 8. This catches an opt-out recorded on the conversation but not yet on the contact property |
| 11 | The agent's STOP step is not set up | FAILED | Not sent: this RCS agent's STOP step is not set up, so a STOP reply could not be recorded. Open RCS Studio in HubSpot (link), open the agent and finish the setup guide. | Finish the setup guide for the agent. See Create and set up your agent |
| 12 | RCS Studio refused the send with a 403 | FAILED | RCS Studio refused the send — the account may be suspended. Check the account in RCS Studio. | Check the account status in RCS Studio, then re-enroll |
| 13 | Any other error while sending | FAILED | The RCS message could not be sent because of an unexpected error. Try again later or contact support. | Try again later. The send is attempted once and never retried automatically, so a contact is not texted twice |
For a FAILED run HubSpot also shows the action's own message: "The RCS message failed to send. Check the RCS Studio logs for details."
Checks 6 to 9 use the phone and consent that HubSpot sends with the run, so a skipped contact costs no extra HubSpot call.
Running the same step twice
Running the same step twice never sends twice. If HubSpot runs the same step again after it already sent, the first send is not repeated and the same Message ID is reported (Send Status SUCCESS, Not Sent Reason empty). If the first run is still in progress, HubSpot is told to retry shortly and the retry reports the first run's result. This can also happen after checks 10 and 11, when the run is claimed just before sending.
If a run started more than 60 seconds ago and never finished, it is FAILED with "A previous attempt of this action run may already have sent the message, so it was not sent again." Check the contact's timeline before you re-enroll, so the contact is not messaged twice.
Large enrollments
HubSpot queues large enrollments and runs the action as contacts move through, so a big campaign finishes over time. The app writes each contact's timeline entry when it sends to that contact, not afterwards.
Contacts who have not opted in
The action never sends to a contact who has not opted in to the agent. The workflow continues for that contact and nothing is sent. The contact gets SKIPPED_NO_CONSENT if the agent is not in their RCS Consent — Opted In property, or SKIPPED_OPTED_OUT if it is in their RCS Consent — Opted Out property. The reason shows in the workflow history and in Not Sent Reason.
The action reads those two properties. It messages the contact only if your agent is in the first and not in the second. It does not read the agent's opt-in list. The list follows the properties only while its switch is on, and you may have no list at all, so the properties are the source of truth. If you keep consent only in a HubSpot list or your own field, copy it into RCS Consent — Opted In first. See Consent management.
Keep them out at enrollment
Filter enrollment on consent, as in Step 1.
Reach them another way
To message contacts who are not opted in, branch on Send Status after the action:
- Add an If/then branch after Send RCS Message.
- Branch on Send Status is any of
SKIPPED_NO_CONSENT. - On that branch, send an email or SMS fallback, or a message that invites them to opt in with your JOIN link.
Do not branch SKIPPED_OPTED_OUT contacts into a message that promotes RCS. A contact who opted out should hear nothing on this channel.
Get consent first
Enroll contacts only after the opt-in is recorded on their record.
| How | Use it when | Page |
|---|---|---|
| JOIN link or QR code | People opt in themselves, from an email, a web page or a printed code | Collect future consent |
| Consent API | Your own form collects the opt-in and you send it to the app | Collect future consent |
| Keyword | A contact texts the opt-in keyword to the agent | Collect future consent |
| Record one number or import a CSV | You already hold consent, for one person or for many contacts | Add your existing consent |
Recording consent in the app is controlled by the consent switches on the Settings tab. They are off by default, so only a HubSpot super admin can record opt-ins until one turns them on. See Manage your team in HubSpot.
What the app writes to the contact timeline
The app writes entries to a contact's activity timeline for the messages it sends, the replies it receives, and the messages that fail or expire. No feature switch controls them, and you read them on the contact record in HubSpot. To see them, open a contact record and look in the Activity tab for RCS Message Event entries. Each entry shows the agent and its details. Consent changes are written as RCS Consent Event entries, covered in Collect future consent.
A message is Failed when RCS reports that delivery failed. It is Expired when RCS reports that it was not delivered within its delivery window.
| Entry | Written when | What it shows |
|---|---|---|
| RCS Message Event (outbound) | The app sends a message successfully: a workflow's Send RCS Message action, the agent's automatic reply to a customer's text, the opt-in prompt and the end-of-chat message, or a reply typed by someone on your team in the HubSpot inbox | Direction, Agent, Sent by, and the template. A reply from your team also shows its Text |
| RCS Message Event (inbound) | A customer texts the agent or taps a button, and the app can match the number to a contact | Direction, Agent, and the customer's Text or the Button tapped |
| RCS Message Event (Failed) | RCS reports that delivery failed | Agent, the template, and the Reason reported by Vibes or the carrier |
| RCS Message Event (Expired) | RCS reports that the message was not delivered within its delivery window | Agent and the template |
Sent by has three values:
| Value | Meaning |
|---|---|
| Workflow Action | A workflow sent it |
| Bot Response | The agent's flows sent it: a reply to the customer's text, the opt-in prompt, or the end-of-chat message sent when a conversation is closed |
| Agent Response | Someone on your team replied from the HubSpot inbox |
Messages from the customer show no Sent by line.
What is not written
- Skipped sends and failed workflow runs. A contact who is skipped (no phone number, opted out, no consent and so on) or a send that fails before it reaches RCS writes nothing.
- Delivered and read receipts. A normal message is one entry when it is sent, and delivery is implied. Only a failure or an expiry gets a second entry.
- Inbox events. Handing a conversation to the inbox, closing it and reopening it write no entry of their own. The end-of-chat message that closing sends is its own Bot Response entry.
- Messages from a number that matches no contact. The customer's text and the agent's reply are not written until the number belongs to a contact, which happens when the person opts in, opts out by
STOPor taps No, Thanks. The number is matched in either Phone Number or Mobile Phone Number. - Failures and expiries for a contact the app has not messaged before. These entries are written only when the app has already messaged the contact, by a workflow send or a Chat with agent escalation. A customer's text alone does not count.
Use failures in workflows and lists
Failed and expired entries are on the contact record, so you can use them as filters or triggers in HubSpot workflows and lists. For example, enroll contacts whose last RCS message failed so your team can follow up another way. Inside the workflow that sends the message, branch on the Send Status output instead.
Troubleshooting
| Problem | Cause | Fix |
|---|---|---|
| RCS Agent shows No RCS agents yet | No agent exists for this account | Open RCS Studio in HubSpot and create a brand and agent. See Create and set up your agent |
| An agent shows (setup needed) | Its STOP step is not set up (the step that records a contact's STOP reply), and its description starts with ⚠ | Finish it in the setup guide before you send |
| An agent's description says "⚠ No inbox connected" or "⚠ No consent list" | Information only | Nothing: these agents can still send |
| RCS Flow shows only Finish this agent's setup first | The selected agent is not set up | Finish setup, then choose the flow again |
| Template Parameters says No parameters defined for this template | The flow declares none | Leave Set Parameters empty, or add parameters to the flow in RCS Studio |
| A value is missing in the message | The line was dropped or the key does not match | Check the key spelling and that the line is key=value |
Everyone is SKIPPED_NO_CONSENT | Consent is kept in a list or your own field, not on RCS Consent — Opted In | Import or record the consent so the property is set |
| A contact opted in but is still skipped | The opt-in was for a different agent | Check which agent is in the contact's RCS Consent — Opted In property |
A contact is SKIPPED_OPTED_OUT but wants messages | They opted out | They must opt back in, for example with your JOIN link. Or record new consent you hold with the re-opt-in override, a checkbox that lets you opt in someone who previously opted out. See Add your existing consent |
| A contact received a message after opting out | The contact opted out after the run started, or the opt-out was not yet recorded on the contact | Check the contact's RCS Consent — Opted Out property and timeline |
| The status is SUCCESS but nothing arrives | The agent is in Test Mode and the device has not accepted the tester invite, or the message failed or expired after sending | Check the contact's timeline for a failed or expired entry and its reason. Then see Test Mode in Create and set up your agent |
| No timeline entry for a message you sent from a workflow | The send was skipped or failed before it reached RCS | Check the action's output in the workflow history |
| A customer's reply is not on the timeline | No contact has that number in Phone Number or Mobile Phone Number | Add the number to a contact |
Next
Updated 9 days ago