Send SMS Action

Send an SMS from the sipgate account behind the AI Flow to any phone number. Useful for delivering confirmation codes, booking summaries, or follow-up links while (or after) a call.

Availability

send_sms is only available upon request and after a positive review by sipgate support (fraud / scam protection). Ask your sipgate contact to enable SMS sending for your account.

Action Structure

{
  "type": "send_sms",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "phone_number": "4915112345678",
  "message": "Your confirmation code is 4242."
}

Fields

Field	Type	Required	Description
type	string	Yes	Always "send_sms"
session_id	string (UUID)	Yes	Session identifier from the event
phone_number	string	Yes	Recipient number in E.164 format — digits only, without leading + (preferred; a leading + is accepted and stripped automatically). Matches the format used by transfer and outbound calls.
message	string	Yes	SMS body. No hard length limit; long texts are billed per standard SMS segment.

Sender

The sender shown to the recipient is determined by following rules:

1. If your account has already outbound calls enabled, the sender is the same as for outbound calls.
2. Otherwise the recipient sees the called number of the current session (i.e. the number the user dialed to reach you).

You cannot override the sender per request.

Delivery Semantics

• SMS sending is fire-and-forget: the call is not blocked waiting for delivery confirmation.
• There is no delivery receipt in the event stream. Use your own monitoring if you need per-message confirmation.
• A failed send does not interrupt the call — the agent can still speak, hang up, or transfer. You receive an sms_failed event to react conversationally (e.g. apologize, retry, or collect a corrected number).

Examples

Python

@app.route('/webhook', methods=['POST'])
def webhook():
    event = request.json

    if event['type'] == 'user_speak':
        text = event['text'].lower()
        if 'send me the code' in text:
            return jsonify({
                'type': 'send_sms',
                'session_id': event['session']['id'],
                'phone_number': event['session']['from_phone_number'],
                'message': 'Your confirmation code is 4242.',
            })

Node.js

app.post('/webhook', (req, res) => {
  const event = req.body;

  if (event.type === 'user_speak' && /code/i.test(event.text)) {
    return res.json({
      type: 'send_sms',
      session_id: event.session.id,
      phone_number: event.session.from_phone_number,
      message: 'Your confirmation code is 4242.',
    });
  }
});

Go

if strings.Contains(strings.ToLower(text), "code") {
    action := map[string]interface{}{
        "type":         "send_sms",
        "session_id":   session["id"],
        "phone_number": session["from_phone_number"].(string),
        "message":      "Your confirmation code is 4242.",
    }
    json.NewEncoder(w).Encode(action)
}

Phone Number Format

Align with the rest of the AI Flow API:

• ✅ 4915112345678 (preferred; E.164 without +)
• ✅ +4915112345678 (accepted; + is stripped before delivery)
• ❌ +49 151 1234 5678 (spaces and dashes rejected)
• ❌ 0151 1234 5678 (national format rejected)

Handling Failure — the sms_failed Event

When sending fails, the AI Flow emits an sms_failed event to your webhook / WebSocket. Handle it to keep the conversation natural:

{
  "type": "sms_failed",
  "session": { "id": "550e8400-e29b-41d4-a716-446655440000", "...": "..." },
  "recipient": "4915112345678",
  "reason": "sender_not_allowed",
  "message": "SMSC returned faultCode 403"
}

reason is one of:

Value	Meaning
sender_not_allowed	Your configured sender number isn't verified for SMS — fix in account settings.
insufficient_balance	Account has insufficient credits for the send.
no_sms_extension	No SMS extension is provisioned for this account — contact sipgate support.
smsc_unavailable	Transient infrastructure issue; safe to retry later.
unknown	Any other failure; check the optional message field for details.

See Events Reference for the full event schema.

Best Practices

1. Ask for consent before sending. Announce over the call that you'll send an SMS.
2. Use E.164 with a leading +. Always normalize user-provided numbers before passing them in.
3. Keep messages short. Each SMS segment is billed; long messages split into multiple segments silently.
4. Handle sms_failed. Have a fallback (speak an apology, retry with a corrected number, or skip the SMS and continue).
5. Don't loop. A single SMS per session is usually enough — sending multiple in quick succession can look spammy.

Next Steps

• Event Types — including the sms_failed event schema
• Speak Action — acknowledge the SMS over the call
• Hangup Action — wrap up after the SMS is queued