sms_tool_documentation

SMS Tool for ElevenLabs Agents

Overview

The SMS tool allows ElevenLabs agents to send SMS messages to callers during conversations. This is particularly useful for sending confirmation codes, order numbers, appointment details, or follow-up information.

Features

✅ Send SMS messages to Canadian phone numbers only
✅ Automatic caller ID detection from conversation context
✅ Rate limiting to prevent spam (3 per conversation, 10 per hour per number)
✅ Full audit logging of all SMS attempts
✅ Clear success/failure feedback to agents

Webhook Endpoint

URL: https://api.triluna.app/api/sms/webhook
Method: POST
Content-Type: application/json

Request Format

{
  "agent_id": "agent_xxxxx",
  "message": "Your order #12345 will be ready in 30 minutes",
  "conversation_id": "{{conversation_id}}",
  "caller_number": "{{customer_phone_number}}"
}

Response Format

Success Response

{
  "success": true,
  "message": "SMS sent successfully to +1416...1234",
  "details": {
    "recipient": "+1416...1234",
    "message_length": 45,
    "provider": "twilio",
    "sid": "SMxxxxx"
  }
}

Error Response

{
  "success": false,
  "error": "Cannot send SMS: Service is only available for Canadian phone numbers",
  "details": {
    "caller_country": "US",
    "caller_number": "+12125551234"
  }
}

Adding SMS Tool to an Agent

Method 1: Using the Utility Script

cd /var/www/triluna.app/utilities
node add-sms-tool-to-agent.js agent_xxxxx

Method 2: Manual Configuration in ElevenLabs Console

Go to your agent in ElevenLabs console

Add a new webhook tool with these settings:

Name: send_sms
URL: https://api.triluna.app/api/sms/webhook
Method: POST
Headers: Content-Type: application/json

Body template:

{
  "agent_id": "YOUR_AGENT_ID",
  "message": "{{message}}",
  "conversation_id": "{{conversation_id}}",
  "caller_number": "{{customer_phone_number}}"
}

Method 3: Via API

const smsTool = {
  type: 'webhook',
  name: 'send_sms',
  description: 'Send SMS to Canadian callers',
  webhook: {
    url: 'https://api.triluna.app/api/sms/webhook',
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: {
      agent_id: 'agent_xxxxx',
      message: '{{message}}',
      conversation_id: '{{conversation_id}}',
      caller_number: '{{customer_phone_number}}'
    }
  }
};

Agent Prompt Instructions

Add this to your agent’s system prompt:

You have the ability to send SMS messages to Canadian callers using the send_sms tool. 
Guidelines for using SMS:
- Always ask for permission before sending an SMS
- Clearly state what information you will send
- Inform the caller if their number is not Canadian and SMS cannot be sent
- Keep messages concise and include only essential information
- Use SMS for: confirmation numbers, appointment details, addresses, reference codes

Usage Examples

Example 1: Order Confirmation

Agent: "Your pizza order is confirmed. Would you like me to send you an SMS with the order details?"
Caller: "Yes, please."
Agent: [Uses send_sms tool with message: "Hell Crust Pizza Order #12345. Ready in 30 min. Pickup at 800 12th St, New Westminster."]
Agent: "I've sent you an SMS with your order confirmation."

Example 2: Appointment Booking

Agent: "Your appointment is booked for tomorrow at 2 PM. Shall I send you a confirmation SMS?"
Caller: "That would be great."
Agent: [Uses send_sms tool with message: "Appointment confirmed: Sept 26, 2 PM at 123 Main St. Reply CANCEL to cancel."]
Agent: "Perfect! I've sent you the appointment details via SMS."

Example 3: Non-Canadian Number

Agent: "Would you like me to send you an SMS confirmation?"
Caller: "Yes, my number is 212-555-1234"
Agent: [Tool returns error about non-Canadian number]
Agent: "I apologize, but our SMS service is currently only available for Canadian phone numbers. I can provide the information verbally instead."

Rate Limits

Per Conversation: Maximum 3 SMS messages
Per Number Per Hour: Maximum 10 SMS messages
Message Length: 1600 characters (automatically truncated if longer)

Database Logging

All SMS attempts are logged in the agent_sms_logs table with:

Agent ID
Conversation ID
From/To numbers
Message content
Status (sent/failed/blocked)
Error messages (if any)
Twilio message SID (if successful)
Timestamp

Troubleshooting

Common Issues

“Caller ID is not available”
- The conversation doesn’t have a valid caller phone number
- Solution: Ask the caller for their phone number manually
“Service is only available for Canadian phone numbers”
- The caller’s number is not Canadian
- Solution: Inform the caller and provide information verbally
“SMS limit reached for this conversation”
- Already sent 3 SMS in this conversation
- Solution: Inform caller the limit is reached
“Failed to send SMS message”
- Twilio API error
- Check Twilio account status and balance
- Verify phone number format

Security Considerations

Phone numbers are validated and sanitized
Messages are truncated to prevent abuse
All attempts are logged for audit
Rate limiting prevents spam
Agent verification ensures only active agents can send SMS

Canadian Area Codes Supported

204, 226, 236, 249, 250, 289, 306, 343, 365, 367, 403, 416, 418, 431, 437, 438, 450, 506, 514, 519, 548, 579, 581, 587, 604, 613, 639, 647, 705, 709, 742, 753, 778, 780, 782, 807, 819, 825, 867, 873, 879, 902, 905

Testing

Use the test script to verify the webhook is working:

node /var/www/triluna.app/test-sms-webhook.js

Support

For issues or questions about the SMS tool, check:

API logs: pm2 logs triluna-production-api
Database logs: SELECT * FROM agent_sms_logs ORDER BY created_at DESC LIMIT 10;
Twilio console for message status