telnyx-messaging-hosted-curl
Set up hosted SMS numbers, toll-free verification, and RCS messaging. Use when migrating numbers or enabling rich messaging features. This skill provides REST API (curl) examples.
team-telnyx · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add team-telnyx/ai --skill telnyx-messaging-hosted-curlAbout this skill
name: telnyx-messaging-hosted-curl description: >- Set up hosted SMS numbers, toll-free verification, and RCS messaging. Use when migrating numbers or enabling rich messaging features. This skill provides REST API (curl) examples. metadata: author: telnyx product: messaging-hosted language: curl generated_by: telnyx-openapi-pipeline
Telnyx Messaging Hosted - curl
Installation
# curl is pre-installed on macOS, Linux, and Windows 10+
Setup
export TELNYX_API_KEY="YOUR_API_KEY_HERE"
All examples below use $TELNYX_API_KEY for authentication.
Error Handling
All API calls can fail with network errors, rate limits (429), validation errors (422), or authentication errors (401). Always handle errors in production code:
# Check HTTP status code in response
response=$(curl -s -w "\n%{http_code}" \
-X POST "https://api.telnyx.com/v2/messages" \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"to": "+13125550001", "from": "+13125550002", "text": "Hello"}')
http_code=$(echo "$response" | tail -1)
body=$(echo "$response" | sed '$d')
case $http_code in
2*) echo "Success: $body" ;;
422) echo "Validation error — check required fields and formats" ;;
429) echo "Rate limited — retry after delay"; sleep 1 ;;
401) echo "Authentication failed — check TELNYX_API_KEY" ;;
*) echo "Error $http_code: $body" ;;
esac
Common error codes: 401 invalid API key, 403 insufficient permissions,
404 resource not found, 422 validation error (check field formats),
429 rate limited (retry with exponential backoff).
Important Notes
- Phone numbers must be in E.164 format (e.g.,
+13125550001). Include the+prefix and country code. No spaces, dashes, or parentheses. - Pagination: List endpoints return paginated results. Use
page[number]andpage[size]query parameters to navigate pages. Checkmeta.total_pagesin the response.
Send an RCS message
POST /messages/rcs — Required: agent_id, to, messaging_profile_id, agent_message
Optional: mms_fallback (object), sms_fallback (object), type (enum: RCS), webhook_url (url)
curl \
-X POST \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "Agent007",
"to": "+13125551234",
"messaging_profile_id": "550e8400-e29b-41d4-a716-446655440000",
"agent_message": {}
}' \
"https://api.telnyx.com/v2/messages/rcs"
Returns: body (object), direction (string), encoding (string), from (object), id (string), messaging_profile_id (string), organization_id (string), received_at (date-time), record_type (string), to (array[object]), type (string), wait_seconds (float)
Generate RCS deeplink
Generate a deeplink URL that can be used to start an RCS conversation with a specific agent.
GET /messages/rcs/deeplinks/{agent_id}
curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/messages/rcs/deeplinks/{agent_id}?phone_number=%2B18445550001&body=hello%20world"
Returns: url (string)
List all RCS agents
GET /messaging/rcs/agents
curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/messaging/rcs/agents"
Returns: agent_id (string), agent_name (string), created_at (date-time), enabled (boolean), profile_id (uuid), updated_at (date-time), user_id (string), webhook_failover_url (url), webhook_url (url)
Retrieve an RCS agent
GET /messaging/rcs/agents/{id}
curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/messaging/rcs/agents/550e8400-e29b-41d4-a716-446655440000"
Returns: agent_id (string), agent_name (string), created_at (date-time), enabled (boolean), profile_id (uuid), updated_at (date-time), user_id (string), webhook_failover_url (url), webhook_url (url)
Modify an RCS agent
PATCH /messaging/rcs/agents/{id}
Optional: profile_id (uuid), webhook_failover_url (url), webhook_url (url)
curl \
-X PATCH \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-H "Content-Type: application/json" \
"https://api.telnyx.com/v2/messaging/rcs/agents/550e8400-e29b-41d4-a716-446655440000"
Returns: agent_id (string), agent_name (string), created_at (date-time), enabled (boolean), profile_id (uuid), updated_at (date-time), user_id (string), webhook_failover_url (url), webhook_url (url)
Check RCS capabilities (batch)
POST /messaging/rcs/bulk_capabilities — Required: agent_id, phone_numbers
curl \
-X POST \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "TestAgent",
"phone_numbers": [
"+13125551234"
]
}' \
"https://api.telnyx.com/v2/messaging/rcs/bulk_capabilities"
Returns: agent_id (string), agent_name (string), features (array[string]), phone_number (string), record_type (enum: rcs.capabilities)
Check RCS capabilities
GET /messaging/rcs/capabilities/{agent_id}/{phone_number}
curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/messaging/rcs/capabilities/{agent_id}/+13125550001"
Returns: agent_id (string), agent_name (string), features (array[string]), phone_number (string), record_type (enum: rcs.capabilities)
Add RCS test number
Adds a test phone number to an RCS agent for testing purposes.
PUT /messaging/rcs/test_number_invite/{id}/{phone_number}
curl \
-X PUT \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-H "Content-Type: application/json" \
"https://api.telnyx.com/v2/messaging/rcs/test_number_invite/550e8400-e29b-41d4-a716-446655440000/+13125550001"
Returns: agent_id (string), phone_number (string), record_type (enum: rcs.test_number_invite), status (string)