Configure outgoing SMS in Vapi
Set up a Vapi API Request tool to send outgoing SMS through your Atom SMS service. The assistant collects the recipient and message then sends the request after the user confirms them.
The tool uses the Atom SMS HTTPS endpoint and a reusable Bearer Token credential. Voice calls use a separate connection; you can test this SMS tool through a Vapi Talk session.
Before you begin
Make sure you have:
- Access to create and manage an SMS service in the Atomic portal.
- Access to create tools and credentials in Vapi.
- A Vapi assistant that will use the SMS tool.
- A sender number or Sender ID authorised for your Atom SMS service.
- A mobile number you control for the test.
Keep your API key secure: Store it in the Vapi credential. Do not include it in the tool URL, request body, assistant instructions, screenshots, support tickets or chat messages.
If you already have an SMS service and active API key, continue to Enable Automation to check the service settings.
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.
Step 3: Select Add Service.
Step 4: Complete the required service details and create the service. Use a clear name that identifies its Vapi use.
Generate the API key
Step 1: Return to the SMS service list, find the service you created then select Manage.
Step 2: In the SMS service, open API Keys and select Generate API Key.
Step 3: When the Success! message appears, select Close. A new row appears under API Keys with the name field empty.
Step 4: To add an optional name, select the pencil icon in the new row, enter a name such as
Vapi 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.
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.
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.
Step 3: Append
/sms/send to the copied URL. If it ends in /api, the full endpoint ends in /api/sms/send.2 of 2 rows
| SMS API URL | https://sms.example.com/api |
| SMS send URL | https://sms.example.com/api/sms/send |
Use the URL shown in your service. The completed path must end in
/api/sms/send, with /api included once.Create the API Request tool
Navigate: Tools > Create Tool > API Request in Vapi.
Step 1: Sign in to Vapi and select the organisation that contains your assistant.
Step 2: Open Tools.
Step 3: Select Create Tool then choose API Request.
Step 4: Under Base Configuration, enter these settings:
4 of 4 rows
| Tool Name | send_sms |
| Description | Sends the SMS requested by the user after confirming the recipient and exact message |
| Request URL | The SMS send URL from the previous section |
| Request HTTP Method | POST |
Keep the tool open while you configure its credential and request body.
Add the API key as a Vapi credential
Step 1: In the tool, find the Authorization section and select Add New.
Step 2: In Server Configuration, select Add Custom Credential. If the correct credential already exists, return to the tool and select it instead.
Step 3: Choose Bearer Token and enter these settings:
4 of 4 rows
| Credential Name | A clear name such as Atomic SMS (Bearer Token) |
| Header Name | Authorization |
| Include Bearer Prefix | On |
| Token | Paste the API key from your Atom SMS service. Enter the key only; Vapi adds the Bearer prefix when Include Bearer Prefix is On. |
Step 4: Select Save to save the credential.
Step 5: Select that credential for the API Request tool. If Add New opens Integrations, return to Tools, reopen send_sms and recheck the Base Configuration settings before continuing.
Vapi adds the bearer authentication from the selected credential. Do not add another
Authorization header under Request Headers. The credential contains the Atom SMS API key, separate from a Vapi API key.Add the body parameters
Step 1: In the API Request tool, open Request Body.
Step 2: Select Add Property to create
to. Set its type to String, make it required and enter the description below. Select Apply.Step 3: Select Add Property again to create
text. Set its type to String, make it required and enter the description below. Select Apply.3 of 3 rows
to | Recipient | Request Body: collected from the user | The mobile number confirmed by the user, in the international format accepted by the Atom SMS service without spaces |
text | Message | Request Body: collected from the user | The exact plain-text SMS message requested and confirmed by the user |
from | Sender | Static Body Fields: fixed value | The sender number or Sender ID authorised for this Atom SMS service |
Step 4: Under Static Body Fields, select Add Field. Set the key to
from, the type to String and the value to your authorised sender number or Sender ID.Use one fixed sender for this basic setup. The assistant collects
to and text; Vapi adds the configured from value to the outgoing request.Step 5: Check that the request will contain
to, text and the fixed from value. Keep the API key in the selected credential.Step 6: If a content-type header is required by your configuration, add
Content-Type with the value application/json under Request Headers.Step 7: Select Publish to make the tool available to your assistant. In the review popup, select Next, enter a Version Name then select Publish.
Attach the tool to the assistant
Step 1: Open the Vapi assistant that will send SMS.
Step 2: Open its Tools settings and add
send_sms.Step 3: Select the Latest version of the tool.
Step 4: Add this instruction to the assistant's instructions:
Only call send_sms when the user asks to send an SMS. Read the recipient number digit by digit and repeat the exact message, then ask for confirmation. If either is unclear, ask the user to correct it before sending. After the tool runs, report the actual result. If Atom accepted the message for processing, say it was submitted. Do not claim delivery until delivery is confirmed. If the request failed or its result is unclear, do not claim success or send it again automatically.
Step 5: Select Publish to open the review popup. Review the changes then select Next to continue. Complete the publication flow so the version used for the test includes the tool and instructions.
These are the basic settings for one sender and one recipient per request. You can adapt how the recipient and message are collected for your use case. Keep the sender authorised for the service.
Test the SMS tool
Step 1: Open the assistant and start a Talk session or call the assistant if its voice connection is already configured.
Step 2: Ask it to send one SMS to a mobile number you control. Say the destination digits clearly and provide a short message, such as
Vapi SMS test. Reply not required.Step 3: Check the recipient number and exact message repeated by the assistant. Confirm only if both are correct.
Step 4: In Vapi, open Logs then select Calls and open the test session or call.
Step 5: Inspect the tool event under Messages and confirm that
send_sms ran with the intended to and text values.Step 6: Inspect the resolved request under the call's Logs tab, when available, to check the fixed
from value and Atom response. Static fields may not appear in the model-generated tool arguments.Step 7: Check that Atom accepted the request and that the SMS arrives on the destination phone.
Acceptance and delivery: A completed Vapi tool call or successful Atom API response does not by itself confirm handset delivery. If the result is pending or unclear, check the message status in Atomic before sending again.
Troubleshooting
8 of 8 rows
| HTTP 401 or 403 | Check the selected Atom SMS credential and authorised sender |
| Wrong endpoint or HTTP 404 | Use the SMS API URL from the same service and ensure the path ends in /api/sms/send once |
| HTTP 400 or 415 | Check the required fields, JSON body and Content-Type header |
| Tool does not run | Check that send_sms is published, attached to the intended assistant and covered by its instructions |
| Wrong recipient or message | Compare the transcript with the tool arguments and correct the read-back before confirming another send |
| Sender is missing or wrong | Check the fixed from value under Static Body Fields and the resolved request |
| Dashboard tool test reports a browser network error | Inspect the server-side assistant call and its logs to determine whether the request reached Atom |
| Tool completed but delivery is unknown | Check the Atom message status before retrying to avoid a duplicate SMS |