Configure outgoing SMS in LiveKit

SMS

Connect a LiveKit AI agent to your Atom SMS service using an HTTP tool and the Atom SMS API. The agent collects the recipient and message then calls the tool after the user confirms them.

This guide covers outgoing SMS from LiveKit Agent Builder. It does not configure incoming SMS or two-way replies. SMS uses an HTTPS request to Atom, separate from the voice SIP trunk.

Before you begin

Make sure you have:

Access to create and manage an SMS service in the Atomic portal.
Access to your LiveKit Cloud project with permission to create or edit agents in Agent Builder.
An SMS API URL for your SMS service in Atomic.
The API key generated for that Atom SMS service.
A sender number or Sender ID authorised for the Atom SMS service.
A mobile number you control for the test.

Request URL: Copy SMS API URL from Service Details in Atomic then append /sms/send. Use the API key generated for the same SMS service.

Keep your API key secure: Store it as a LiveKit secret. Do not include it in prompts, tool descriptions, screenshots, support tickets or chat messages.

If you already have the SMS service and an active API key, continue to Enable Automation to check the service settings. Use the SMS API URL and API key from the same SMS service.

Create the SMS service

Navigate: Services > SMS in the Atomic portal.

Step 1: Sign in to the Atomic portal.

Step 2: In the sidebar, open Services then select SMS.

Open SMS from the Services menu in Atomic

Step 3: Select Add Service.

Select Add Service to create an SMS service

Step 4: Complete the required service details and create the service. Use a clear name that identifies its LiveKit use.

Generate the API key

Step 1: Return to the SMS service list, find the service you created then select Manage.

SMS service list with the Manage button highlighted for the service you created.

Step 2: In the SMS service, open API Keys and select Generate API Key.

LiveKit SMS service settings with the Generate API Key button highlighted

Step 3: When the Success! message appears, select Close. A new row appears under API Keys with the name field empty.

API Keys table showing the new active key with an empty optional name field.

Step 4: To add an optional name, select the pencil icon in the new row, enter a name such as LiveKit in the Add key name... field then select the save icon.

Step 5: Select Show in the new row, copy the API key and store it securely.

Use the API key from this Atom SMS service for the SMS_API_KEY secret in LiveKit.

Enable Automation

Step 1: Scroll to Manage Service at the bottom of SMS Service Configuration.

Step 2: Set Automation to On and leave Block Service set to Off.

Step 3: Select Update.

Step 4: Refresh the page and confirm that Automation is On and Block Service is Off.

Save the API key as a LiveKit secret

Navigate: Your LiveKit Cloud project > Agents > Agent Builder.

Step 1: Sign in to LiveKit Cloud and open Agents.

Step 2: Select Start in browser with Agent Builder. If you already have an Agent Builder agent, open it and continue to Step 4.

LiveKit Agents page with the Start in browser with Agent Builder card highlighted

Step 3: In Create new agent, select Generic assistant then select Create.

LiveKit Create new agent dialog with Generic assistant selected and the Create button available

This guide uses Generic assistant as a starting template. The agent will use the send_sms HTTP tool added in the next section to send SMS.

Step 4: Open the agent's Secrets settings and select Add secret.

LiveKit agent Secrets page with the Add secret button highlighted

Step 5: Enter SMS_API_KEY as the secret name, enter the API key generated for this Atom SMS service then save the secret.

LiveKit Secrets dialog with the API key name and value fields ready to save

You will reference this secret in the HTTP tool header as Bearer {{secrets.SMS_API_KEY}}. If you use a different secret name, update the reference to match.

Copy the SMS API URL

Navigate: Your SMS service in Atomic > Service Settings > Service Details.

Step 1: Return to the SMS service you created in Atomic.

Step 2: Under Service Details, select COPY next to SMS API URL.

Copy the SMS API URL from Service Details

Step 3: Append /sms/send to the copied URL. If it ends in /api, the full endpoint ends in /api/sms/send.

For example, https://sms.example.com/api becomes https://sms.example.com/api/sms/send. Use the URL from your own SMS service.

Create the SMS HTTP tool

Navigate: Your agent > Builder > Actions > HTTP tools.

Step 1: Open the agent's Builder and then select Actions.

LiveKit agent Builder with the Actions tab selected.

Step 2: Under HTTP tools, select Add HTTP tool.

LiveKit Builder Actions tab with the Add HTTP tool button highlighted under HTTP tools

Step 3: Enter these settings:

LiveKit Add HTTP tool form with the URL field highlighted for the SMS endpoint

4 of 4 rows


Tool name	`send_sms`
HTTP method	`POST`
Endpoint URL	The SMS API URL copied from Atomic with `/sms/send` appended
Description	Sends the SMS requested by the user after confirming the recipient and exact message

Use the full SMS endpoint from the Copy the SMS API URL section above. The final URL ends in /api/sms/send. Add /api only once.

Step 4: Under Headers, select Add header. Enter the text below in the Name and Value fields. Repeat for the second header.

HTTP tool editor with two Authorization header name and value rows highlighted

2 of 2 rows


`Content-Type`	`application/json`
`Authorization`	`Bearer {{secrets.SMS_API_KEY}}`

Step 5: Under Parameters, select Add parameter. Fill in Name, Type and Description and set Required to Yes as shown below. Repeat for each parameter.

Add HTTP tool dialog with required parameter fields and the Add parameter button highlighted

3 of 3 rows


`to`	`string`	The confirmed recipient's mobile number with its country code and no leading `+` or spaces	Yes
`from`	`string`	The exact sender number or Sender ID authorised for this Atom SMS service	Yes
`text`	`string`	The exact plain-text message requested and confirmed by the user	Yes

Include the approved sender value in the from parameter description so the agent uses that value. Do not let it invent a sender.

Step 6: Add this instruction to the tool description:

Use this tool only when the user requests an SMS. Repeat the recipient number and exact message and ask for confirmation before sending. If either is unclear, ask the user to correct it. Use only the configured sender. After the tool runs, report the actual result. Say the message was submitted only when the Atom SMS API response confirms acceptance. Do not claim handset delivery from acceptance alone or automatically repeat an unclear request.

Step 7: Select Update tool and confirm that Builder has saved the change.

Deploy the agent

Step 1: In Builder, select Deploy agent.

Builder Actions screen with the Deploy agent button highlighted.

Step 2: If a deployment environment is requested, select the environment you intend to use.

Step 3: Wait for deployment to finish.

Step 4: Open Versions.

LiveKit Builder screen with the Versions navigation item highlighted for step 4.

Step 5: Confirm that the new version is deployed in the intended environment.

Versions page showing demoSmsV001 deployed to production.

Saving the HTTP tool does not update an existing deployed version. Deploy again after changing the endpoint, secret reference, parameters or tool instructions.

Test the SMS tool in Console

Step 1: In Builder, select Test in Console to open the same agent's Console.

LiveKit Builder with the Test in Console button highlighted for the selected agent.

Step 2: Confirm that Console is using the deployment you updated.

Step 3: Select Start session and wait until the session is connected and the agent has joined.

LiveKit agent console with the Start a session button highlighted for step 3

Step 4: If you want to type the request, turn off the microphone.

Step 5: Enter a request using a mobile number you control, with its country code and no leading + or spaces. For example, ask the agent to send the message LiveKit SMS test. Reply not required. to your test number.

LiveKit console chat with the request field and Send message button highlighted

Step 6: Select Send message.

Step 7: Check the recipient and message repeated by the agent. Confirm the send only if both are correct.

Step 8: Open Events and find the latest Function tools executed event for send_sms.

LiveKit console Events tab with the event log for checking send_sms execution

Step 9: Check the recipient, sender and message in the request. Confirm that the Atom SMS API response contains status: success and one or more message_id values. A pending message status means delivery has not yet been confirmed.

Step 10: Check that the SMS arrives on the destination phone. If delivery is unclear, check the message status in Atomic before trying again.

A successful HTTP response alone does not confirm that Atom accepted the SMS. Check the Atom SMS API response as well as delivery to the handset. Do not repeat a request until you know what happened to the first message.

Troubleshooting

6 of 6 rows


No `send_sms` event	Confirm the tool was saved, the agent was deployed after the change and Console is using that deployment
HTTP 502	Ask your integration owner to check the request URL and API response before retrying
HTTP 401 or 403	Check the API key for your Atom SMS service, the LiveKit secret reference and the authorised sender
Events shows `from_`	Check the outgoing request body with your integration owner. Atom requires a field named `from`; resolve any field-name mismatch before retrying.
Wrong sender, recipient or message	Correct the parameter descriptions, save, redeploy and start a fresh Console session
Agent reports success but the tool failed	Use the tool result to determine the outcome and check Atomic before sending again

For telephone calls to the agent, see Configure an Atom number in LiveKit.

Was this article helpful?

Configure outgoing SMS in ElevenLabs

Configure outgoing SMS in Vapi

Create and Use SMS Templates