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

{
  "direction": "inbound",
  "sid": "callrsid",
  "from": "+33639980042",
  "to": "+33639980044",
  "body": {
    "text": "Hello world!"
  },
  "trafficType": "marketing",
  "status": "delivered",
  "encoding": "gsm",
  "parts": 1,
  "network": "20801",
  "cost": "2.00",
  "paymentType": "prepaid",
  "delivered": "2024-04-24T17:42:28Z",
  "created": "2024-04-24T17:42:28Z",
  "updated": "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?

📌 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