SMS

It's common to want customers to text your agent. For instance, a customer texts your support number "What is your return policy?", and the agent answers by SMS. The telnyx connector does this on your own Telnyx number.

Answer by SMS

Add the telnyx connector to your agent:

name: support
mode: text
llm: llm-smart
connectors:
  - name: telnyx
    connection: acme-sms # the label of your Telnyx connection

You need three things from Telnyx: an API key, a number with messaging in E.164, and your account's public key. The public key is under Keys & Credentials > Public Key in the Telnyx portal. Setup takes four steps:

curl -fsSL https://getstream.io/cli/beta/install.sh | bash # the agents commands are in the beta CLI
echo "$TELNYX_PUBLIC_KEY" | getstream agents connectors client set telnyx --provider-app-id "$TELNYX_PROFILE_ID" --signing-secret -

echo "$TELNYX_API_KEY" | getstream agents connections create telnyx --label acme-sms --input phone_number=+12025550100 --token -

getstream agents sync support

From a phone, text "What is your return policy?" to your Telnyx number. The reply comes back by SMS, from the same number.

In the Dashboard

Steps 2 and 3 work in the Dashboard too. In the Stream Dashboard, go to Agents > Library > Connectors and open Telnyx.

1. Click Set OAuth client. The dialog has two fields: fill Provider app ID with the profile ID and Signing secret with the public key, then click Save client.
2. Click Create connection. Owner starts on Signed-in user: pick App. Type acme-sms in Label, your number in phone_number and the API key in Token, then click Create connection. The connection's page opens, and the connection is connected.

US phones need 10DLC

Telnyx explains the registration in Getting Started with 10DLC, and 10DLC explains what it is.

Replies to a phone in Canada are delivered without a 10DLC campaign.

Conversations

• Each phone is one conversation. The agent reads the earlier texts from that phone.
• Telnyx answers STOP, START and HELP, not the agent.
• After STOP, the person gets no reply until they text START.

Remind by SMS

The agent can remind a customer later, by SMS. Text "Remind me in 2 minutes to check my order status". The agent confirms, and about 2 minutes later the reminder arrives by SMS, once.

Reminders need scheduling on, so create support-sms with the last call in With the API instead of syncing agent.yaml. One connection serves one agent, so delete a synced support first.

A text has no time zone, so on a customer's first reminder the agent asks for their city and works out their time zone from it. We recommend llm-smart for reminders.

With the API

Your server can do the setup instead of the CLI. First, find your number's messaging profile at Telnyx:

curl -g -H "Authorization: Bearer $TELNYX_API_KEY" \
  "https://api.telnyx.com/v2/phone_numbers?filter[phone_number]=%2B12025550100"

Write the number's + as %2B. Telnyx returns the profile ID as messaging_profile_id. Set it as PROFILE_ID, then point the profile's webhook URL at Stream:

curl -X PATCH "https://api.telnyx.com/v2/messaging_profiles/$PROFILE_ID" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"webhook_url\": \"$STREAM_ACCELERATION_URL/v1/connectors/events/telnyx/$PROFILE_ID\"}"

Then save your Telnyx account and create the connection. $SERVER_TOKEN is a server token:

curl -X PUT "$STREAM_ACCELERATION_URL/v1/agents/connectors/telnyx/oauth-client" \
  -H "api_key: $STREAM_API_KEY" -H "stream-auth-type: jwt" \
  -H "Authorization: Bearer $SERVER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"provider_app_id": "<profile ID>", "signing_secret": "<public key>"}'

curl -X POST "$STREAM_ACCELERATION_URL/v1/agents/connections" \
  -H "api_key: $STREAM_API_KEY" -H "stream-auth-type: jwt" \
  -H "Authorization: Bearer $SERVER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"connector_id": "telnyx", "owner": {"type": "app"}, "label": "acme-sms", "inputs": {"phone_number": "+12025550100"}}'

curl -X PUT "$STREAM_ACCELERATION_URL/v1/agents/connections/$CONNECTION_ID/credentials" \
  -H "api_key: $STREAM_API_KEY" -H "stream-auth-type: jwt" \
  -H "Authorization: Bearer $SERVER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expected_revision": 1, "values": {"token": "<Telnyx API key>"}}'

$CONNECTION_ID is the id the second call returns. After the third call, the connection is connected.

For reminders, create the agent with this call. Put the connection's id in connection_id:

curl -X POST "$STREAM_ACCELERATION_URL/v1/agents/configs" \
  -H "api_key: $STREAM_API_KEY" -H "stream-auth-type: jwt" \
  -H "Authorization: Bearer $SERVER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "support-sms", "mode": "text", "llm": "llm-smart",
       "instructions": "Answer briefly. When asked for a reminder, schedule it with schedule_task, then confirm briefly.",
       "scheduling": {"enabled": true},
       "connectors": [{"name": "sms", "connector_id": "telnyx", "connection": {"type": "fixed", "connection_id": "<connection ID>"}, "tools": []}]}'

When a text gets no answer

Going further