Description

Bi-way for n8n

Send SMS, RCS rich messages and emails from n8n: cards and carousels with images,
suggestion buttons, your verified brand as the sender, and a fallback SMS when a phone cannot receive
RCS.

RCS is the successor of SMS in the phone’s messaging app: messages come from your brand’s verified
profile, the RCS agent, and can show images, cards and buttons. n8n-nodes-biway-messenger is the
n8n community package of Bi-way, the messaging platform of Pocket
Communication. Its nodes are verified by n8n: install them from
the nodes panel, on n8n Cloud or self-hosted. In French, see the
Bi-way page for n8n.

> RCS is currently available on French mobile operators only (French phone numbers). For other
> numbers, and for phones that cannot receive RCS, Bi-way can send an SMS instead, or let your
> workflow decide (see RCS with your own fallback).

• Why Bi-way in n8n
• Get an API key
• Installation
• Credentials
• Send your first message
• Channels
• Requirements
• Declare your RCS agent
• Operations
• Bi-way Trigger
• RCS with your own fallback
• RCS scenarios
• Example workflows
• Compatibility
• API documentation and support

Why Bi-way in n8n

• Two-way conversations. The Bi-way Trigger starts a workflow when a customer replies or taps a

suggestion button, and tells you which button. Delivery and read reports arrive the same way, so a
workflow can follow up on messages that were not delivered or not read.

• RCS with a safety net. When a phone cannot receive RCS, Bi-way sends the fallback SMS of your

account, an SMS written in the node, or nothing at all so that your workflow decides.

• The same cards by email. A card or a carousel can also go by email, laid out by Bi-way. Its

buttons open the Bi-way web chat, where your keyword replies and the Bi-way Trigger answer as they
do on RCS.

• A verified sender. RCS messages come from your RCS agent: your brand name and logo, verified by

Google and approved by the mobile operators.

• Your data stays in France. Bi-way is run by Pocket Communication, a French company subject to

the GDPR, and hosted in France. With a self-hosted n8n, phone numbers and messages only travel
between your servers and Bi-way: no third-party automation cloud is involved.

Get an API key

1. Create your Bi-way account: v3.bi-way.fr/signup. API access is
included. The free plan sends SMS, with prepaid credits; RCS needs the Pro plan and an RCS agent
(see Declare your RCS agent); email is set up separately. To change the
plan of an existing account, contact Bi-way.
2. In the Bi-way app, open Settings › Security › API keys
(v3.bi-way.fr/settings/security).
3. Click Create a key, give it a name (for example n8n), and copy the token and the
secret. The secret is shown only once.

You can revoke a key at any time from the same page; the workflows that use it then stop working.
The page also lists the Account key: it works too, but cannot be revoked, so prefer a key of your
own.

Installation

The Bi-way nodes are verified by n8n, so they install from the editor, on n8n Cloud and self-hosted:

1. As the owner or an admin of the instance, open the nodes panel (+) and search for Bi-way.
2. Open the node with the verified badge and click Install node.

One installation serves the whole instance: every member can then use the nodes.

A self-hosted instance that does not show verified nodes can install the package from **Settings ›
Community Nodes › Install**: enter n8n-nodes-biway-messenger and confirm. See the n8n
installation guide for the manual
installation (queue mode, Docker images built in advance).

Credentials

The Bi-Way API credential uses the API key: paste the token and the secret created in
Get an API key. Leave Base URL unchanged unless Bi-way support asks you to
change it. n8n tests the key when you save the credential.

Send your first message

1. Add the Bi-way node to a workflow (search for “Bi-way”, “SMS”, “RCS” or “Email”).
2. Pick your Bi-Way API credential, then Resource Message and Operation Send.
3. Channel: one of the channels of your account (see Channels), for example RCS
or an SMS channel.
4. Content Text, Source Raw Message, and type the Body.
5. Recipient: a phone number in international format, for example +33612345678 (an email
address on an email channel, with a Subject).
6. Click Execute step. The node returns the id of the sending; the status reports of the Bi-way
Trigger carry it as order_id.

Channels

The Channel list shows the channels enabled on your Bi-way account, under the names Bi-way gives
them:

• RCS: rich messages (cards, carousels, buttons) to French mobile phones, sent by your RCS agent,

with a fallback SMS for the phones that cannot receive RCS. Listed once your RCS agent is created
(see Declare your RCS agent).

• SMS: text only, from the short or long number set up on your account. Whether customers can

reply depends on that number: ask Bi-way which of your channels receive replies.

• Email: text with attachments, cards and carousels, through the email channel (Mailjet) or

the email_smtp channel (your SMTP server).

A channel is enabled on your account by Bi-way. The node only offers what the chosen channel can
carry: an SMS channel only takes a text.

Requirements

| What you use | Needs |
|—|—|
| Message › Send, Message › Broadcast | A Bi-way account (sign-up includes API access) and enough credits: Bi-way refuses a sending that the credits of a prepaid account do not cover. Channels that need a sender use the default sender of your account unless you pick one. |
| RCS: channel, cards, carousels, buttons, keyword replies, scenarios | A plan with RCS, recipients on French mobile operators, and an RCS agent declared by your company and launched by the operators: see Declare your RCS agent. |
| Email channels | The email option of your account, set up by Bi-way: Mailjet for email, SMTP for email_smtp. |
| Template, Asset, Contact and Entry operations | The matching permissions on your Bi-way user profile. |
| Bi-way Trigger | An n8n instance reachable from the internet over HTTPS. |

When something is missing, the node stops with a message that says what to do.

Declare your RCS agent

RCS messages come from your RCS agent: the name, logo and description of your brand, verified by
Google and approved by each French mobile operator. Bi-way handles the procedure:

1. Declare the agent on the RCS declaration form, or from
the RCS settings of the Bi-way app (v3.bi-way.fr/settings/chatbot).
A declaration fee applies.
2. Bi-way processes the declaration and creates the agent. The RCS channel then appears in the
Channel list of the node.
3. Each operator approves and launches the agent. Send by SMS in the meantime.

RCS Agent › Get Status returns the state of the declaration, the state of the agent at each
operator, launched and the nextStep to take. The RCS Agent State Changed event of the Bi-way
Trigger starts a workflow when an operator changes the state of your agent.

Until the agent is launched:

• No agent yet: Bi-way refuses RCS messages, and the node says that your account has no RCS agent.
• Agent launched by no operator: Bi-way accepts the message. The node shows a warning and its output

carries warnings; the message goes out as the fallback SMS if there is one, otherwise it is not
delivered and nothing is debited. Status reports carry fallbackreason: "agentnot_launched".

• Agent launched by some operators only: the recipients of the other operators get the fallback

SMS if there is one; the fallback_reason of their status reports tells why.

Operations

| Resource | Operation | What it does |
|—|—|—|
| Message | Send | Sends a text, a card or a carousel to one phone number or email address, written in the node or taken from a template. |
| Message | Broadcast | Sends the same content to phone numbers or email addresses, contacts and contact groups, now or later, optionally in segments. |
| Template | Create | Creates a message template: a subject (used by email), then a text (with RCS buttons if needed), a card or a carousel. Reuses the template with the same title by default. |
| Asset | Upload | Uploads a file to your Bi-way gallery (2 MB for images and documents, 30 MB for videos). Returns its ID, to show it in a card or attach it to an email. |
| Contact | Create | Creates a contact from the columns of your account. Recognizes an existing contact by the column you pick in Match On Column (the phone number by default, or the email address, a customer number…) and, by default, returns it instead of creating a duplicate (or updates it, or stops). |
| Contact | Create Group | Creates a contact group. Reuses the group with the same name by default. |
| Contact | Import File | Imports contacts from a file into a group, in one of the import formats of your account (XLS by default; the CSV format of Bi-way is tab-separated). The import runs in the background: the node returns the ID of the import task. |
| Entry | Get | Returns a record of your account from its type and ID (booking, contact…), such as the entry of a share request received by the Bi-way Trigger. |
| RCS Agent | Create Keyword Reply | Replies with a template when a customer taps a Suggested Reply button that carries the keyword. A keyword typed in the conversation does not trigger it: catch typed messages with the Bi-way Trigger. Reuses the reply to the same keyword by default. |
| RCS Agent | Get Status | Returns the state of your RCS declaration and of your RCS agent at each operator, and the next step to take. |
| RCS Scenario | Create, Get, Get Many, Activate, Deactivate, Delete | Manages the scenarios of your RCS agent (see RCS scenarios). Create, Get and Get Many return a simplified output unless you turn Simplify off. Delete removes the scenario only, not its templates nor its keyword replies. |
| RCS Scenario | Start | Sends the first message of a scenario to a phone number. |

Good to know:

• Content, then Source: Send and Broadcast first ask for the Content (Text, Card or

Carousel), then whether you write it in the node (Raw Message) or use a Template. The
template list only shows the templates of the chosen content that the channel can carry; any other
template is refused before sending.

• Cards and carousels need an RCS or email channel. A card has an image or a video (from your

Bi-way gallery, where it must be public, or from an HTTPS address), a title, a body and 4 buttons
at most; a carousel shows 2 to 10 cards side by side. An RCS text takes 11 buttons at most. Button
labels are 25 characters at most. Button kinds: Suggested Reply, Open URL Action, Dial Action and
View Location Action.

• Emails written in the node need a Subject; an email sent from a template takes the

template’s subject. The body of a text email is HTML. Attachments are files of your Bi-way gallery:
upload a file of the workflow first with Asset › Upload.

• Recipients: phone numbers in international format, or email addresses on email channels.

Addresses typed in Broadcast are not saved as contacts.

• Personalization tags work for contacts and contact groups: write a contact column between

brackets, for example Hello [surname] for the first name of a Bi-way contact.

• Picking items: templates, contact groups, scenarios and gallery files are chosen From List

(search by name or ID) or By ID, for example to map an ID returned by an earlier node.

• Dates are sent to Bi-way in the Europe/Paris time zone, to the minute. A date without time zone

is read in the time zone of the workflow. Bi-way refuses dates in the past.

• Status reports: Broadcast asks for delivery and read reports by default (option **Status

Reports*). They reach the Bi-way Trigger as Message Status Updated* events.

• No duplicates when a workflow runs again: Template › Create, Contact › Create Group, Contact ›

Create and RCS Agent › Create Keyword Reply reuse the existing item by default (field **If …
Already Exists**). Names are compared ignoring case and surrounding spaces; contacts on the exact
value of their Match On Column. Update It changes the mapped columns only.

• The node can be used as a tool by AI agents.

Bi-way Trigger

The trigger registers its webhook URL on your Bi-way account when the workflow is published (activated,
on n8n 1), and removes it when the workflow is unpublished. It adds its URL next to the callback URLs
your account may already have: it never replaces them. Listen for test event registers a separate
test URL for as long as n8n listens; it also has to be reachable from the internet (for an n8n on your
computer, use a tunnel and set WEBHOOK_URL).

| Event | Starts the workflow when |
|—|—|
| Message Status Updated | A message you sent was delivered, read, refused, clicked or expired, or could not go through RCS. |
| Message Received | A customer sent a message, replied to one of your messages or tapped a suggestion button. |
| Contact Import State Changed | A contact import progressed or ended. |
| RCS Agent State Changed | Your RCS agent changed state at a mobile operator. |
| RCS Capability Check Completed | Bi-way finished checking which phone numbers can receive RCS. |
| Account State Changed | Your Bi-way account was enabled or disabled. |
| Share Request Received | A visitor of one of your share links booked, cancelled a booking, sent a form, chose an item of a list, answered a questionnaire or updated their details. |

Each event becomes one item. Bi-way calls the webhook once and does not send an event again, whatever
the answer: events sent while your n8n cannot be reached are lost.

Share Request Received items carry the action (bookingdone, canceldone, input_done,
interested, answer, subscribe, update, unsubscribe) and its action_name, the share and
the function of the share link (id, name), the visitor when known (type, id, name), the
details the share link attached for its notifications (data: the booked resource, the begin date and
duration of a booking, the answers…), and entry: the type and id of the record of the request —
the booking, the record sent through a form, the item chosen in a list, or the contact. With the
Share Actions and Share IDs options, the workflow only starts for the actions and share links
you list.

Do not rely on data: its fields and formats change from one action to another, and a value can differ
from the record (the duration of a booking, for example). For reliable values, read entry with
Entry › Get.

Message Received items carry the customer’s phone number (address), the name of the contact
when Bi-way knows it, otherwise the phone number (sender), the text (message), the channel, the
date, and keyword: the keyword of the button the customer tapped, or null for a typed message.
With the Button Keywords option, the workflow only starts for the buttons you list.

Message Status Updated items carry the order_id (the id returned by Message › Send or
Broadcast), the messageid, the channel, the recipient’s address, the dates sentat,
deliveredat and readat, and a status:

| status | Meaning |
|—|—|
| sent, error | The message left Bi-way, or could not. |
| delivered, undelivered, rejected | Delivery report of the operator. |
| read, open, click, … | Read report, for the channels that have one. |
| unsupported | RCS was not possible (phone not RCS-capable) and no SMS was sent: handle it in your workflow. |
| expired | The RCS message was not delivered before its expiry. |

They also carry fallback: "sms" when a fallback SMS was sent instead of the RCS message, "none"
when no SMS was sent, null otherwise. When Bi-way falls back to SMS, an event with
status: "error" and fallback: "sms" can arrive shortly before the sent of the SMS: do not treat
it as final, wait for the delivery report.

With fallback comes fallbackreason: agentnot_launched when your RCS agent is launched by no
operator, notrcscapable when the phone is not known as RCS-capable, rcssendfailed when it is but
the sending failed, for example because your agent is not launched at the operator of this recipient.

Good to know:

• Bi-way sends the events of the whole account, including messages not sent from n8n.
• The webhook URL must be reachable from the internet over HTTPS. When n8n runs behind a proxy or

a tunnel, set the WEBHOOK_URL environment variable of n8n.

• The registered URL carries a token derived from the secret of the API key; calls without it are

refused. If you change the secret of the credential, unpublish the workflow and publish it again.

RCS with your own fallback

By default, when a phone cannot receive RCS, Bi-way sends the fallback SMS of your account, with the
STOP mention and the link to the Bi-way web chat as your account sets them. With Send This SMS, you
write the text in the node and choose them in Fallback SMS Options. Both are on by default and add
11 and 35 characters to an SMS limited to 160: 114 are left for your text.

To decide in n8n instead:

1. Bi-way node, Message › Send on the RCS channel, with If the Phone Is Not RCS-Capable
set to Send Nothing.
2. In another workflow, Bi-way Trigger with the event Message Status Updated → If
{{ $json.status }} is unsupported → Bi-way node, Message › Send on an SMS channel to
{{ $json.address }}, or anything else: a call task, a different wording, nothing at all.

RCS scenarios

A Bi-way scenario is a conversation driven by RCS buttons: each Suggested Reply button sends a
keyword, and a keyword reply answers it with the next message. Build one from n8n in four steps:

1. Template › Create for each step: content Text, Card or Carousel, with buttons of type
Suggested Reply. Each button carries a keyword (for example CONFIRM, CALL_ME).
2. RCS Agent › Create Keyword Reply for each keyword: it sends the template of the next step.
3. RCS Scenario › Create with the first template. The scenario appears in the Bi-way app, where
you can also edit it.
4. RCS Scenario › Start to send the first message to a phone number.

To take over the conversation in n8n, give the last templates Suggested Reply buttons whose keywords
have no keyword reply, and catch them with a Bi-way Trigger on Message Received with the
Button Keywords option. The workflow receives the customer’s phone number (address) and the
tapped keyword (keyword), and can answer with Message › Send or run any other action.

Example workflows

Ready-to-import workflows are in examples/, with how to import them and the
placeholders to replace. They use n8n’s own nodes and the Bi-way nodes, and send by RCS: without an
RCS agent, switch their Bi-way nodes to an SMS channel (Content Text instead of Card).

!The Appointment reminder example in the n8n editor: the daily reminder, then the Bi-way Trigger receives the answer and a Switch routes it

| Workflow | What it does |
|—|—|
| Appointment reminder | Reminds customers of tomorrow’s appointments with quick-reply buttons, then handles their answers. |
| Review request | Asks for a rating, shares your Google review link with everyone who answers and alerts your team about low ratings. |
| Order notifications | Sends an RCS card with a tracking button when a WooCommerce order is completed, with a fallback SMS. |
| Inbound reply to team inbox | Routes customer replies to the right team by keyword. |
| Form to welcome message | Creates or updates the contact from a form and sends a welcome message. |
| Weezevent ticket holders | Fetches the new participants of a Weezevent event, saves them as contacts and sends them an RCS message, or an email when the registration form does not ask for their phone number. Needs a Weezevent API key: Weezevent grants them to its partners, ask them for one. |

Compatibility

• Verified by n8n: installable from the nodes panel on n8n Cloud and self-hosted.
• Tested with n8n 2.45.4, self-hosted. On n8n 1, “publish” and “unpublish” read “activate” and

“deactivate”.

• n8n nodes API version 1, no runtime dependency.
• RCS reaches phones on French mobile operators only; SMS reach the destinations of your Bi-way plan.

API documentation and support

• Bi-way page for n8n, in French: requirements, installation, use cases.
• Bi-way API documentation, for the requests behind each

operation and the advanced Extra (JSON) and Filters (JSON) options.

• RCS declaration form
• n8n community nodes documentation
• Issues and questions about this package:

GitHub issues

• Bi-way support: [email protected]

License

MIT © Pocket Communication