SMS Channel

Overview

SMS uses the same authentication, idempotency, signing secret, and response shape as every other channel — just a different event type and an extra routing field (to_phone).

Inbound vs. outbound

Supported actions

SMS supports only the send_message action. The react, unreact, and typing_on actions are Meta-only and are rejected when used with an SMS conversation.

Pure-relay mode

To handle all SMS conversations yourself with no AI from ChatGenius, either disable the SMS AI Assistant under Settings → SMS → AI Assistant (SMS-only), or enable Global External Reply Mode to pause AI across every channel at once (see Global External Reply Mode). With relay on:

• Inbound SMS still hits your endpoint with the full payload — signed, validated, ready to process
• ChatGenius does not generate any AI reply
• You can still send replies via the Send-Reply API (using to_phone or conversation_id)
• The conversation and message history are still recorded in your portal so your team has visibility

Inbound Payload

When a customer texts your provisioned ChatGenius number, ChatGenius forwards an sms.message_received event with the standard envelope plus an SMS-specific message.sms sub-block. source.channel is always twilio_sms.

{
  "event_id":    "7f7a80c84bf17c4b5b72974c97365a77",
  "event_type":  "sms.message_received",
  "occurred_at": "2026-04-27T23:22:10Z",
  "source": {
    "platform": "sms",
    "channel":  "twilio_sms"
  },
  "conversation": {
    "id": 119301
  },
  "customer": {
    "platform_user_id": "+15551234567",
    "phone":            "+15551234567"
  },
  "message": {
    "id":          "SMdb4342728f73bca6a83770a705e27b31",
    "text_raw":    "Hi, what time do you open Saturday?",
    "attachments": [],
    "sms": {
      "to_phone":     "+15559876543",
      "from_phone":   "+15551234567",
      "num_segments": 1,
      "num_media":    0,
      "encoding":     "GSM-7"
    }
  },
  "meta": {
    "version":         "v1",
    "payload_profile": "full",
    "generated_at":   "2026-04-27T23:22:10Z"
  }
}

SMS-specific fields

Signature verification, retry behavior, and timestamp validation are identical to every other channel — same X-SumGenius-Signature header, same per-account signing secret, same algorithm. See Verifying Signatures.

Sending SMS

Send an SMS by calling the same Send-Reply endpoint used for DMs, with to_phone instead of conversation_id. The platform is auto-set to sms.

Request body

The sender number is automatically set to your provisioned sms_phone_number. You cannot specify from_phone — sender selection is server-controlled to enforce A2P 10DLC compliance.

curl -X POST https://sumgenius.ai/api/meta/webhook-send.php \
  -H "X-SumGenius-Api-Key: sgwh_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotency_key": "refill-reminder-001",
    "action":          "send_message",
    "to_phone":        "+15551234567",
    "message_text":    "Your prescription is ready for pickup. Reply STOP to opt out."
  }'

SMS-specific success response fields

SMS responses follow the same Response Format as DM responses, with these additions:

Encoding & Segments

SMS uses two encodings depending on the characters in your message body. ChatGenius detects the encoding automatically and validates against the corresponding cap.

Quota counting rules

• Inbound SMS — free, never counted (regardless of segments)
• Outbound SMS — each successful Send-Reply API call counts as 1 toward your monthly quota, regardless of how many segments Twilio splits the message into
• A 200-char GSM-7 message = 1 quota unit (Twilio sends 2 segments; we count 1)
• A 200-char UCS-2 message = 1 quota unit (Twilio sends 3 segments; we count 1)

Opt-out handling (STOP / START)

SMS opt-out is handled automatically at multiple layers — you don't implement any of this:

• Twilio carrier-level Advanced Opt-Out: when a recipient texts STOP, Twilio blocks all future outbound SMS to that number from your Messaging Service, regardless of any application-layer check.
• ChatGenius app-level fast-fail: we mirror the opt-out so future API calls return 410 with "Recipient has opted out (replied STOP)." immediately, without consuming a Twilio API call.
• Re-subscription: if the recipient texts START, UNSTOP, or YES, both layers re-enable sending automatically.

You should still include opt-out language in your initial messages (e.g. "Reply STOP to opt out.") to comply with carrier and CASL/TCPA requirements.

SMS Error Reference

SMS errors follow the same general error response shape. The codes specific to SMS are:

Permanent failures (invalid recipient, opted out, over-length) are not retried — they go straight to dead_letter. Transient failures (Twilio 5xx, 429, network errors) are retried with the same backoff schedule used for Meta deliveries.