Guides
SupportLogin
Start typing to search…

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

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

      - action: sms@v1
        params:
          to:
            - ${{ sms.fromNumber }}
          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:

sms:
  sid: callrsid
  direction: inbound
  fromNumber: "+33639980042"
  fromType: MOBILE # libphonenumber types
  fromCountry: FR
  fromLocation: France
  toNumber: "+33639980044"
  toType: MOBILE
  toCountry: FR
  toLocation: France
  status: delivered # created|error|expired|failed|pending|delivered|remote-queued|sent
  encoding: gsm # gsm|unicode
  bodyText: Hello, this is an inbound SMS!
  parts: 1
  billingDebit: "1.00" # cents
  billingPaymentType: prepaid # prepaid|postpaid
  network: ""
  deliveredAt: "2025-03-31T15:42:00.123Z"
  createdAt: "2025-03-31T15:42:00.123Z"
  updatedAt: "2025-03-31T15:42:00.123Z"
  sentAt: null

You can use this to:

  • Route logic based on keywords
  • Track senders by number or location
  • Auto-reply or forward the SMS via fetch@v2

✅

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 Portal
  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.0",
    "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 8 days ago