n8n
Send and receive SMS in n8n with the official textbee node: install, credentials, sending, the SMS trigger, delivery status and AI Agent tool use.
Updated
textbee has an official n8n community node. It sends and receives SMS in your workflows through your own Android phone. The package is @textbee/n8n-nodes-textbee on npm. It is open source, MIT licensed, source at github.com/textbee/n8n-nodes-textbee.
The package has two nodes:
| Node | What it does |
|---|---|
| textbee | Sends SMS (one message or bulk), reads message history, lists devices, reads account totals and manages webhook subscriptions. The n8n AI Agent can use it as a tool. |
| textbee Trigger | Starts a workflow when your phone receives an SMS, or when a sent SMS is sent, delivered or fails. |
Prerequisites
- An n8n instance. Self-hosted n8n can install the node now. For n8n Cloud, see Install the node.
- A textbee.dev account with a registered Android device
- An API key from the dashboard. Create a separate key for n8n, so you can revoke it on its own later.
Install the node
Self-hosted n8n
- Go to Settings > Community Nodes.
- Select Install.
- Enter
@textbee/n8n-nodes-textbee. - Agree to the risks and select Install.
To install it when the instance starts, for example in Docker or a deployment pipeline, set this environment variable:
N8N_COMMUNITY_PACKAGES='[{"name":"@textbee/n8n-nodes-textbee"}]'n8n Cloud
The node is in review for n8n verification. After n8n approves it, you add it from the nodes panel in n8n Cloud. Until then, use the HTTP Request node method on n8n Cloud. It does the same work with built-in nodes.
Add the credential
Create a credential of the type Textbee API. It needs only your API key:
| Field | Required | Value |
|---|---|---|
| API Key | Yes | Your API key from the dashboard. See API keys. |
| Base URL | No | Leave it empty for textbee.dev. The default is https://api.textbee.dev. For a self-hosted textbee server, enter its address. The node adds /api/v1 itself. |
| Webhook Signing Secret | No | Leave it empty. The textbee Trigger then creates a random secret for each workflow. Set it (at least 20 characters) only if you need one secret for all workflows. When set, every trigger on this credential uses it. |
One credential works for both nodes. The key stays in the n8n credential store, so an exported workflow does not contain it.
Operations
| Resource | Operations |
|---|---|
| Message | Send, Send Bulk, Get Many, Get, Get Batch |
| Device | Get Many, Get |
| Account | Get (totals for sent and received SMS, devices and API keys) |
| Webhook Subscription | Create, Get, Get Many, Update, Delete, Get Notifications |
The textbee Trigger starts on these events: MESSAGE_RECEIVED, MESSAGE_SENT, MESSAGE_DELIVERED, MESSAGE_FAILED and UNKNOWN_STATE. Webhook events describes the payload of each one.
Send an SMS
- Add a textbee node.
- Set Resource to Message and Operation to Send.
- Enter the Message and the Recipients. Use international format, for example
+15555550123. Separate more than one number with commas. - Optionally pick a Device. Without one, textbee uses your default device.
- Select Execute step to send a test. The output contains
smsBatchId.
Use expressions to fill the fields from earlier nodes, for example {{ $json.phone }} in Recipients and Hi {{ $json.name }}, your table is ready. in Message.
To send different texts to different people in one call, use Send Bulk. Each entry in Messages has its own text and recipients.
Receive SMS and reply
This workflow answers every incoming text.
- In the textbee Android app, turn on Receive SMS. Without it, the phone does not upload incoming messages.
- Add a textbee Trigger. Pick your credential and select the Message Received event.
- Connect a textbee node with Resource Message and Operation Send. Set Recipients to
{{ $json.sender }}and write the reply in Message. - Publish the workflow.
Each item from the trigger has the payload fields: sender, message, receivedAt, deviceId and idempotencyKey. textbee retries a failed delivery with the same idempotencyKey, so use it to skip duplicates.
No setup in the textbee dashboard
You do not add a webhook in the textbee dashboard. The trigger does it for you:
- When you publish the workflow, the trigger creates a webhook subscription in textbee that points at the n8n production webhook URL.
- When you unpublish the workflow, the trigger deletes the subscription.
- When the URL, the events or the signing secret change, the trigger updates the same subscription. It does not create a second one.
- The subscription name is
n8n: <workflow name> (<n8n host>), so the textbee dashboard shows which n8n instance owns it. - If events stop arriving, publish the workflow again.
Each published workflow with a textbee Trigger uses one webhook subscription. It counts toward the webhook limit of your plan: 5 on Free, 10 on Pro, unlimited on Scale. See Webhook limits by plan.
Signing secret and signature checks
When the credential Webhook Signing Secret is empty, the trigger creates a random secret for each workflow. n8n keeps it in the workflow's static data, and it never appears in node output.
The trigger checks the timestamped signature in the X-Textbee-Signature header on every delivery. It rejects a request with a missing or wrong signature, and a request signed more than 5 minutes ago, with HTTP 401. A captured request cannot be replayed later. See Verify the signature.
- After you upgrade the package to 1.1.0 or later, publish your textbee Trigger workflows again, or restart n8n. The trigger turns on the timestamped signature check when the workflow is published.
- Keep the n8n server clock accurate. Sync it with NTP. A clock that is more than 5 minutes off makes every delivery fail.
- If you change the credential signing secret, publish the workflows again so textbee uses the new secret.
textbee delivers webhooks to public addresses only. An n8n test URL on localhost or a private network does not receive events. In development, expose n8n through a tunnel and set the n8n WEBHOOK_URL environment variable to the tunnel address.
To branch on the text, put a Switch node between the trigger and the send node, for example on {{ $json.message }} for keywords such as STOP or YES.
Delivery status
A successful send means textbee accepted and queued the message. It does not confirm delivery. Follow the status in one of two ways:
- Events: a textbee Trigger on Message Delivered and Message Failed. Each event carries
smsBatchId,recipientandstatus. A failed event also carrieserrorMessage. - Polling: a textbee node with Message > Get Many and the SMS Batch ID filter, or Message > Get Batch.
delivered and failed are final. A message can stay sent when the carrier sends no delivery report. See Delivery status for each state.
Use textbee as an AI Agent tool
The textbee node works as a tool for the n8n AI Agent node.
- Add an AI Agent node and connect a chat model.
- Under Tool, add textbee and pick an operation, for example Message > Send or Message > Get Many.
- Let the model fill the fields that change per run, such as Recipients and Message. Set fixed values for the rest.
Give the agent a rule in its system message, for example to text only numbers from your CRM. An agent with a send tool can send to any number it is given.
Workflow patterns that work well
- Form to SMS: an n8n Form Trigger, then a textbee Send that texts the submitter.
- Reminders on a schedule: a Schedule Trigger, a node that reads tomorrow's rows from a sheet or database, then one textbee Send per row.
- Alerting: an Error Trigger workflow that texts the on-call phone. SMS gets through when email and chat do not.
- Keyword replies: a textbee Trigger on Message Received, a Switch on the message text, and a textbee Send for each branch.
- AI autoresponder: a textbee Trigger, an AI Agent or LLM node that drafts a reply, then a textbee Send back to the sender.
Without the node: HTTP Request and Webhook
The built-in HTTP Request and Webhook nodes also work with textbee. Use this method on n8n Cloud until the textbee node is verified, or when you cannot install community nodes.
Send SMS
- Open Credentials, add Header Auth, set Name to
x-api-keyand Value to your API key. - Add an HTTP Request node:
- Method:
POST - URL:
https://api.textbee.dev/api/v1/gateway/send-sms - Authentication: Generic Credential Type, Header Auth, your credential
- Send Body: on, Body Content Type: JSON, Specify Body: Using JSON
- Method:
- Set the body. Switch the JSON field to expression mode so the
{{ }}values resolve.
{
"recipients": ["{{ $json.phone }}"],
"message": "Hello from n8n"
}Receive SMS
- Add a Webhook node with HTTP Method
POSTand copy its production URL. - In the textbee dashboard, add that URL as a webhook, subscribe to MESSAGE_RECEIVED and set a signing secret.
- Publish the workflow. Each incoming SMS arrives with
sender,messageandreceivedAtin the body.
Verify the X-Textbee-Signature header if the workflow does anything sensitive. The header has the form t=<unix seconds>,v1=<signature>, and the signature is the HMAC-SHA256 of <t>.<body> with your signing secret. Add a Crypto node with Action Hmac, Type SHA256 and this Value:
{{ $json.headers["x-textbee-signature"].split(",")[0].slice(2) }}.{{ JSON.stringify($json.body) }}Then add an If node with two conditions: the Crypto result equals {{ $json.headers["x-textbee-signature"].split(",")[1].slice(3) }}, and {{ Math.abs(Date.now() / 1000 - Number($json.headers["x-textbee-signature"].split(",")[0].slice(2))) }} is at most 300. textbee signs compact JSON, so JSON.stringify of the parsed body gives the same bytes. Details on Webhooks.
Delivery status
Add an HTTP Request node with the same credential:
GET https://api.textbee.dev/api/v1/gateway/messages?smsBatchId=YOUR_BATCH_IDEach message row carries a status. See Message history for the other filters.
Going deeper
The blog has a full tutorial with more patterns: n8n SMS integration with textbee, and a comparison of the same flow in Make and Zapier.
Next steps
- Agent quickstart - The API surface for any automation
- Webhooks - Payload format and signature verification
- MCP server - The same send and read tools for AI assistants
Need help? Check our FAQ or contact support.