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 hereDo this first
You have no agent yet, or its setup guide steps are not doneCreate and set up your agent
You have no flow to sendBuild one in RCS Studio. The action sends an RCS Studio flow (Flows, links and connectors).
Your contacts have not opted inConsent 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 usesAdd 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 ModeRegister 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

  1. In HubSpot, go to Automation > Workflows and create a contact-based workflow, or open one.
  2. 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

  1. Select + to add an action and search for RCS Studio.
  2. Select Send RCS Message.

Step 3: Choose the agent and flow

FieldWhat to enter
RCS AgentThe agent to send from. An agent that is not set up shows (setup needed) after its name
RCS FlowThe 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 ParametersRead-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 ParametersValues 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:

OutputMeaning
Send StatusSUCCESS, FAILED, SKIPPED_OPTED_OUT, SKIPPED_NO_CONSENT or SKIPPED_CONSENT_UNVERIFIED
Not Sent ReasonText that says why a contact was skipped or failed. Empty after a successful run
Message IDThe 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.
#CheckSend StatusNot Sent Reason showsFix
1No agent selected, or a placeholder rowFAILEDMissing agentId — select an RCS agent in the workflow action configurationOpen the action and choose a real agent in RCS Agent
2No flow selectedFAILEDMissing message template — select a template in the workflow action configurationChoose a flow in RCS Flow after choosing the agent
3A system flowFAILEDThis 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
4The app is not connected for this portalFAILEDInstallation not configuredReconnect RCS Studio. See Install RCS Studio for HubSpot
5The contact's data could not be readSKIPPED_CONSENT_UNVERIFIEDNot 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
6The contact has no number in the phone field in useFAILEDContact has no Phone Number, or Contact has no Mobile Phone Number, depending on the field in useFill in that property on the contact. A super admin sets which field the app uses in Settings
7The phone number is not validFAILEDContact phone number is invalid or missing country codeStore the number with its country code. A number with no country code is read as a US number
8The contact opted outSKIPPED_OPTED_OUTNot sent: this contact has opted out of messages from this RCS agent.Nothing: do not message them. They can opt back in
9The contact has no opt-inSKIPPED_NO_CONSENTNot 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
10The contact's conversation record holds an opt-outSKIPPED_OPTED_OUTNot 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
11The agent's STOP step is not set upFAILEDNot 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
12RCS Studio refused the send with a 403FAILEDRCS 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
13Any other error while sendingFAILEDThe 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:

  1. Add an If/then branch after Send RCS Message.
  2. Branch on Send Status is any of SKIPPED_NO_CONSENT.
  3. 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.

HowUse it whenPage
JOIN link or QR codePeople opt in themselves, from an email, a web page or a printed codeCollect future consent
Consent APIYour own form collects the opt-in and you send it to the appCollect future consent
KeywordA contact texts the opt-in keyword to the agentCollect future consent
Record one number or import a CSVYou already hold consent, for one person or for many contactsAdd 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.

EntryWritten whenWhat 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 inboxDirection, 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 contactDirection, Agent, and the customer's Text or the Button tapped
RCS Message Event (Failed)RCS reports that delivery failedAgent, 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 windowAgent and the template

Sent by has three values:

ValueMeaning
Workflow ActionA workflow sent it
Bot ResponseThe 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 ResponseSomeone 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 STOP or 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

ProblemCauseFix
RCS Agent shows No RCS agents yetNo agent exists for this accountOpen 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 onlyNothing: these agents can still send
RCS Flow shows only Finish this agent's setup firstThe selected agent is not set upFinish setup, then choose the flow again
Template Parameters says No parameters defined for this templateThe flow declares noneLeave Set Parameters empty, or add parameters to the flow in RCS Studio
A value is missing in the messageThe line was dropped or the key does not matchCheck the key spelling and that the line is key=value
Everyone is SKIPPED_NO_CONSENTConsent is kept in a list or your own field, not on RCS Consent — Opted InImport or record the consent so the property is set
A contact opted in but is still skippedThe opt-in was for a different agentCheck which agent is in the contact's RCS Consent — Opted In property
A contact is SKIPPED_OPTED_OUT but wants messagesThey opted outThey 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 outThe contact opted out after the run started, or the opt-out was not yet recorded on the contactCheck the contact's RCS Consent — Opted Out property and timeline
The status is SUCCESS but nothing arrivesThe agent is in Test Mode and the device has not accepted the tester invite, or the message failed or expired after sendingCheck 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 workflowThe send was skipped or failed before it reached RCSCheck the action's output in the workflow history
A customer's reply is not on the timelineNo contact has that number in Phone Number or Mobile Phone NumberAdd the number to a contact

Next


Did this page help you?