SMS Broadcast System - API Documentation
Full reference for all commands, modes, and webhook endpoints.
In all URLs below, replace XXX with your AI Apps Account ID, found in your account settings.
How Endpoints Work
Two ways to call each endpoint - read this first
App Command (API Call)
POST your request to
Mode / Webhook (Direct URL)
POST directly to the endpoint URL shown in each section. The fields go in the POST body as standard form fields (the same fields you would include in an HTML form POST). Use this method for provider webhooks, website forms, or any third-party system that sends form data. No API key is required - the account ID is part of the URL.
POST your request to
https://api.aiappsapi.com with your API key and account ID in the POST body. The fields described in each section below go inside the jsonData POST field as a JSON-encoded string. Use this method when your server is making the call and you have your API credentials available.Mode / Webhook (Direct URL)
POST directly to the endpoint URL shown in each section. The fields go in the POST body as standard form fields (the same fields you would include in an HTML form POST). Use this method for provider webhooks, website forms, or any third-party system that sends form data. No API key is required - the account ID is part of the URL.
Carrier values used throughout this API:
tmobile, att, verizon, uscellular, boost, other. Always use these exact lowercase values. If you do not know the carrier, pass other.
Provider Webhook URLs
Configure these in your SMS provider dashboard
Each supported provider gets a dedicated webhook URL. Enter this URL in your provider account wherever it asks for a delivery status callback URL, an incoming message URL, or both. If the provider has separate fields for each type, use the same URL in all of them.
Twilio
https://api.aiappsapi.com/XXX/smsbroadcast/twilio
ClickSend
https://api.aiappsapi.com/XXX/smsbroadcast/clicksend
Vonage
https://api.aiappsapi.com/XXX/smsbroadcast/vonage
Plivo
https://api.aiappsapi.com/XXX/smsbroadcast/plivo
Sinch
https://api.aiappsapi.com/XXX/smsbroadcast/sinch
Telnyx
https://api.aiappsapi.com/XXX/smsbroadcast/telnyx
Bandwidth
https://api.aiappsapi.com/XXX/smsbroadcast/bandwidth
Bird (MessageBird)
https://api.aiappsapi.com/XXX/smsbroadcast/messagebird
TextMagic
https://api.aiappsapi.com/XXX/smsbroadcast/textmagic
TextVolt
https://api.aiappsapi.com/XXX/smsbroadcast/volt
Ahoi
https://api.aiappsapi.com/XXX/smsbroadcast/ahoi
ClickBuzz
https://api.aiappsapi.com/XXX/smsbroadcast/clickbuzz
Post Subscriber Data
command: postrecord | mode: smsbroadcastpost
Adds a new subscriber record to your list. This is the primary way to get contacts into the system - from a web form, a data feed partner, or any lead source. Records are stored with full profile information and organized by carrier group for routing.
POST Mode URL (no API key needed)
https://api.aiappsapi.com/XXX/smsbroadcast/smsbroadcastpost
POST App Command URL
https://api.aiappsapi.com app: smsbroadcast command: postrecord
Required Fields
| Field Name | Field Key | Notes |
|---|---|---|
| Phone Number | phone | 10-digit US phone number, no plus sign, no country code. Example: 5551234567 |
| Carrier | carrier | Must be one of: tmobile, att, verizon, uscellular, boost, other. Use other if unknown. |
| Feed Name | feed | A short unique code identifying which data source or campaign this record came from. Used for tracking and filtering. Example: webform-jan |
Optional Fields
| Field Name | Field Key | Notes |
|---|---|---|
| Email Address | Subscriber email address. | |
| First Name | fname | First name only. |
| Last Name | lname | Last name only. |
| Signup URL | sourceurl | The page where this subscriber opted in. Example: yourwebsite.com/offer |
| Opt-In Date | optin | Human-readable date and time the subscriber opted in. Example: 05-01-2025 05:45:00 |
| IP Address | ip | IPv4 or IPv6 address of the subscriber at the time of opt-in. |
| State | state | Two-letter US state code. Example: NY, FL |
| Country | country | Two-letter country code. Example: US |
Unsubscribe a Phone Number
command: smsunsub | mode: smsunsub
Removes a phone number from your active subscriber list and adds it to your suppression file. Once suppressed, that number will not receive any future broadcasts regardless of how it was added. Incoming STOP and END replies are handled automatically by the system, but you can also trigger an unsubscribe manually using this endpoint.
POST Mode URL (no API key needed)
https://api.aiappsapi.com/XXX/smsbroadcast/smsunsub
POST App Command URL
https://api.aiappsapi.com app: smsbroadcast command: smsunsub
Required Fields
| Field Name | Field Key | Notes |
|---|---|---|
| Phone Number | phone | 10-digit US phone number to remove. |
Optional Fields
| Field Name | Field Key | Notes |
|---|---|---|
| Sending Number | sendingNumber | If provided, the unsub is recorded against this specific sending number. If omitted, the phone is suppressed from all sends. |
Send a Single SMS Message
command: sendmessage
Sends an individual SMS message to one phone number immediately. The sending number you specify must already be configured in your account with a valid provider and API key. This endpoint is for on-demand single sends - for sending to a list, use the broadcast scheduling features in the dashboard.
POST App Command URL
https://api.aiappsapi.com app: smsbroadcast command: sendmessage
This command is only available as an App Command. It is not available as a direct mode/webhook URL.
Required Fields
| Field Name | Field Key | Notes |
|---|---|---|
| Phone Number | phone | 10-digit US phone number to send to. |
| Sending Number | sendingNumber | The number the message should appear to come from. Must match a configured sending number in your account. 10-digit format. |
| Message | message | The text of the SMS message to send. Standard SMS length limits apply (160 characters for a single segment). Longer messages are sent as multi-part. |
Enroll in a Responder Series
command: respondercreate
Enrolls a phone number into an automated responder series. Once enrolled, the contact receives a sequence of messages at scheduled intervals, as configured in the series settings in your dashboard. A responder series is different from a broadcast - each subscriber gets their own independent schedule starting from when they enrolled.
POST App Command URL
https://api.aiappsapi.com app: smsbroadcast command: respondercreate
This command is only available as an App Command. It is not available as a direct mode/webhook URL.
Required Fields
| Field Name | Field Key | Notes |
|---|---|---|
| Phone Number | phone | 10-digit US phone number to enroll. |
| Series ID | series | The ID of the responder series to enroll the contact in. Series are created and named in your dashboard. |
| Sending Number | sendingNumber | 10-digit sending number to use for this subscriber's messages in the series. |
Optional Fields
| Field Name | Field Key | Notes |
|---|---|---|
| Start Time | starttime | Unix timestamp for when the first message should go out. If omitted or within the next 10 hours, the first message sends immediately if the subscriber's local hour is between 8am and 6pm. Scheduled for the same hour, not the same minute. |
| First Name | fname | Subscriber's first name. Used for personalization macros in message content. |
| Carrier | carrier | One of: tmobile, att, verizon, uscellular, boost, other. If blank, the system looks up the carrier automatically at a cost of 1 credit. |
| Exclude Carriers | excludeCarriers | Comma-separated list of carriers to skip. If the subscriber's carrier is in this list, enrollment is silently skipped. Example: verizon,tmobile |
| Feed Name | feed | Tracking tag identifying the source of this enrollment. |
Remove from a Responder Series
command: responderunsub
Stops a phone number from receiving further messages in a responder series. You can remove a subscriber from one specific series or from all series at once. This does not add the number to your global suppression list - it only affects the responder schedule. To fully suppress a number from all sends, also call the unsubscribe endpoint.
POST App Command URL
https://api.aiappsapi.com app: smsbroadcast command: responderunsub
This command is only available as an App Command. It is not available as a direct mode/webhook URL.
Required Fields
| Field Name | Field Key | Notes |
|---|---|---|
| Phone Number | phone | 10-digit US phone number to remove from the series. |
Optional Fields
| Field Name | Field Key | Notes |
|---|---|---|
| Series ID | series | The ID of the specific series to remove the subscriber from. If omitted, the subscriber is removed from all responder series. |