Guides
SupportLogin
  1. MESSAGING

Receive SMS

You can handle inbound SMS messages in two powerful ways:

  1. In real-time inside a Callr Actions scenario
  2. Via webhooks usingv2.sms.inbound.received to your backend

This gives you full flexibility — whether you're building flows directly in YAML, or integrating with your own platform.

✅ Option 1 – Handle SMS in a Callr Actions Scenario

Callr Actions supports a special inbound-sms branch, triggered automatically when an SMS is received on a number assigned to your scenario.

🧪 Example: Log and Auto-Reply

compat:
  version: "2025-09-01"

branches:
  inbound-sms:
    actions:
      - action: log@v1
        params:
          message: SMS received ${{ JSON.stringify(sms) }}

      - action: sms@v1
        params:
          to:
            - ${{ sms.from }}
          body: >
            Thanks for your message! We’ll get back to you soon.

📄 The sms Object

When inbound-sms is triggered, you get access to the following predefined object sms. It has the same shape as the SMS object of the REST API and of the webhook payload below:

sms:
  sid: callrsid
  direction: inbound
  from: "+33639980042"
  to: "+33639980044"
  body:
    text: Hello, this is an inbound SMS!
  encoding: gsm # gsm|unicode
  paymentType: prepaid # prepaid|postpaid
  cost: "0.00" # in cents of the account currency
  status: delivered # created|pending|sent|delivered|remote-queued|error|failed|expired
  parts: 1
  trafficType: marketing # marketing|alerting
  created: "2025-03-31T15:42:00Z"
  updated: "2025-03-31T15:42:00Z"
  delivered: "2025-03-31T15:42:00Z" # only when set, like sent, network and error
📘

With compat.version: "2024-04-01", sms keeps its older flat shape (fromNumber, toNumber, bodyText…). See Pre-defined Variables.

You can use this to:

  • Route logic based on keywords
  • Track senders by number
  • Auto-reply with sms@v1, or forward the SMS to your backend with fetch@v3
✅

Make sure the number assigned to your scenario supports SMS.

🌐 Option 2 – Receive SMS via Webhook

If you prefer to handle SMS outside of Callr Actions (e.g. directly in your backend), you can use the v2.sms.inbound.received webhook.

🔔 Webhook Setup

  1. Go to the Webhooks section in the Callr Console
  2. Create a new webhook
  3. Select the event: v2.sms.inbound.received
  4. Provide your HTTPS endpoint URL

📦 Example Payload

{
  "id": "a033174403257076580mk8v4KiGgZA32",
  "at": "2025-04-07T13:29:30.765Z",
  "sid": "pdszbxss",
  "type": "v2.sms.inbound.received",
  "try": 0,
  "payload": {
    "direction": "inbound",
    "sid": "callrsid",
    "from": "+33639983040",
    "to": "+33639980010",
    "body": {
      "text": "Hello world!"
    },
    "trafficType": "alerting",
    "status": "delivered",
    "error": "",
    "created": "2024-04-24T17:42:28Z",
    "delivered": "2024-04-24T17:42:28Z",
    "updated": "2024-04-24T17:42:28Z",
    "sent": "2024-04-24T17:42:28Z",
    "parts": 1,
    "network": "20801",
    "encoding": "gsm",
    "cost": "2.00",
    "paymentType": "prepaid",
    "statusHistory": [
      {
        "after": "delivered",
        "before": "sent",
        "at": "2024-04-24T17:42:28Z"
      }
    ]
  }
}
💡

This webhook is great if you're managing all logic in your backend and don’t need a YAML-based flow.

⚖️ Which Should You Use?

Use CaseRecommendation
Build logic directly in YAML✅ inbound-sms in Callr Actions
Push SMS to your backend system✅ v2.sms.inbound.received webhook
Auto-reply to incoming SMS✅ Either (Callr Actions is easier)
Log SMS in your CRM✅ Either (Callr Actions is easier)

📌 Reminder: Assign an SMS-Compatible Number

Inbound SMS only works on phone numbers that support SMS. You must:

  • Purchase or reserve an SMS-compatible number
  • Assign it to your Callr Actions scenario

Updated 6 days ago

Did this page help you?