Skip to content

Text Message Received

Overview

The Text Message Received trigger starts a workflow when an inbound SMS arrives. It is the SMS counterpart of WhatsApp Message Received and outputs the same shape of data, so a workflow written for one is easy to adapt to the other.

Use it for SMS auto-replies, keyword handling such as STOP and INFO, two-way conversations with customers, and logging inbound texts against the CRM record.

This trigger listens; it does not send

Add an SMS task to reply.

Configuration

Builder fields

The Field column is the label as it appears in the task builder; Key is the name the value is stored under and referenced by.

Field Key Type Default Notes
Receiving number (optional) sms_number select – Options: Any number
Field Required Default Notes
SMS number No blank Leave blank to fire for any inbound SMS. Set a specific receiving number (DID) to scope the trigger to that number.

Number scoping works on Telnyx only

Scoping matches on the number the message arrived at. Telnyx inbound messages carry that destination number; SMS Portal inbound messages do not. A trigger scoped to a specific number therefore never fires for SMS Portal traffic — by design. On SMS Portal, leave the field blank.

Output Fields

Field Description
session_id The sender's number. A stable per-conversation key — use it as the memory key for an AI chat agent.
from_number The sender's number.
message The message text.
message_id The provider's message identifier.
provider Which SMS provider delivered the message.
to_number The receiving number. Empty on providers that do not supply it.
contact_name Matched CRM contact's first name, or empty when unmatched.
contact_surname Matched CRM contact's surname, or empty.
client_id Matched client ID, or empty.
contact_id Matched contact ID, or empty.
thread_id The chat thread this message belongs to.
timestamp When the message was received.
{{task_ID_run}} Always true — the trigger fired.
{{task_ID_run_text}} SMS Message Received trigger executed successfully.

Real-World Examples

Handle a STOP keyword

Text Message Received
  └─ If Statement          message equals "STOP"
      ├─ true ─ Edit Client    set the opted-out field
      │           └─ SMS       confirm the opt-out
      └─ false ─ ... normal handling

Auto-reply with conversation context

Text Message Received
  └─ Chat Thread           read the conversation so far
      └─ AI Prompt         draft a reply, memory key = session_id
          └─ SMS           send it

Log inbound texts on the client record

Text Message Received
  └─ If Statement          client_id is not empty
      └─ Workflow Note     log the message

Best Practices

  • Leave the number blank on SMS Portal. A scoped trigger will never fire there.
  • Handle opt-out keywords first. Put the STOP branch at the top of the workflow so it cannot be missed by a later condition.
  • Handle the unmatched sender. Branch on client_id being empty before using contact fields.
  • Use session_id for AI memory rather than contact_id, which is empty for unknown senders.
  • Mind SMS length and cost when replying — see the SMS task.

Troubleshooting

Symptom Cause and fix
Workflow never fires The task or workflow is disabled, or the trigger is scoped to a number while inbound arrives via SMS Portal, which supplies no destination number. Clear the SMS number field.
Fires for every number The SMS number field is blank. Set it — on Telnyx only.
to_number is empty Expected on providers that do not report the destination number.
client_id and contact_id empty The sender's number is not in the CRM, or is stored in another format. Normalise with Phone Formatter.

Frequently Asked Questions

Does this fire for messages my team sends? No, inbound only.

Is it the same as the WhatsApp trigger? Nearly. The output shape matches, but SMS adds provider, to_number and thread_id, and has no profile name or message type.

Can I run one workflow for both SMS and WhatsApp? Not from a single trigger — each workflow has exactly one trigger. Build one for each, and keep the shared logic in tasks they both call.