SMS API Documentation
This document provides in-depth instructions on how to send & receive text messages using the TextBetter API. We make it easy with flexible end points, on-demand reports, and instant integration capabilities. Ready to dig in? Incoming Messages (V2)Outgoing Messages (V2)Incoming SMS Messages
POST Incoming SMS V2
Introduction
Incoming Messages are sent to Customer’s Endpoint
Metadata
| Method | POST |
| Payload Location / Type | Body / JSON |
| URL | This is provided to us by you |
Body
|
KEY |
TYPE |
DESCRIPTION |
|
id |
String |
Our unique identifier for a message |
|
to |
String |
Your phone number the message was sent to. Usual Format: [Country Code][Area Code][Number] |
|
from |
String |
Who sent you the message. Usual Format: [Country Code][Area Code][Number] |
|
timestamp |
Integer |
EPOCH UTC time of when we received the message |
|
type |
String |
ENUM <SMS/MMS> |
|
text |
String |
The body of the message |
|
contentTypes |
String Array |
The MIME Type of image(s) [“image/jpeg”,”image/jpeg”] |
|
images |
StringArray |
A base64 string of image(s) [“base64 image”,” base64 image”] |
|
filename |
String Array |
an array of image names [“testfile.jpeg”,”testfile2.jpeg”] |
Sample Payloads
SMS
{
"id": "123",
"to": "18003221112",
"from": "14077773456",
"timestamp": "1666798041",
"type": "SMS",
"text": "Hello World"
}MMS
{
"id": "123",
"to": "18003221112",
"from": "14077773456",
"timestamp": "1666798041",
"type": "MMS",
"text": "",
"images": [
{
"Base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=",
"type": "image/png"
}
]
}Response Requirements
We do not read your response body but we do require a status code response of 200 to mark it successfully sent on our side.
Outgoing SMS Messages
POST Send SMS V2
Metadata
| Method | POST |
| Payload Location / Type | Body / JSON |
| URL | https://api2.textbetter.com/api/SendOutgoingMessages |
URL Parameters
| Code | hr1oXwI06ECDoqvGKgaGnc60OyoSFQU7sFII5o1DDy5mAzFuGTeLHQ== |
| Static code to access Azure Function; will not change unless IT tells you it has |
Body
| fromNumber | Your text enabled phone number you want the message sent from. Format: [Country Code][Area Code][Number] | |
| toNumber | Array | Array<String> of phone numbers you wish to send your message to. |
| toNumber[n] | String | The phone number you want the message sent to. Usual Format: [Country Code][Area Code][Number] |
| body | String | The body of the message |
| APIKey | String | Enter the API Key our team provided you |
| filenames | String Array | An array of objects containing a list of images sent . Ex: [“testfile.jpeg”,”testfile2.jpeg”] |
| images | String Array | A base64 encoded string of the image. Ex: [“base64 image”,” base64 image”] |
| contentTypes | String Array | The MIME Type of the image. Ex: [“image/jpeg”,”image/jpeg”] |
Sample Payloads
SMS
curl --location 'https://api2.textbetter.com/api/SendOutgoingMessages?code=hr1oXwI06ECDoqvGKgaGnc60OyoSFQU7sFII5o1DDy5mAzFuGTeLHQ%3D%3D' \
--header 'Content-Type: application/json' \
--data '{
"fromnumber": "15166565102",
"tonumber": ["15167821187"],
"body": "This is a V2 Test G",
"APIKey": "x_notrealapikey"
}'MMS
curl --location 'https://api2.textbetter.com/api/SendOutgoingMessages?code=hr1oXwI06ECDoqvGKgaGnc60OyoSFQU7sFII5o1DDy5mAzFuGTeLHQ%3D%3D' \
--header 'Content-Type: application/json' \
--data '{
"fromNumber": "15166565102",
"toNumber": ["15167821187"],
"body": "This is a V2 Test G",
"APIKey": "x_notrealapikey",
"filenames": ["testimg.jpg"],
"images": ["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"
],
"contentTypes": ["image/jpeg"]
}'Payload Response
We do not read your response body but we do require a status code response of 200 to mark it successfully sent on our side.
SUCCESSFULLY SENT
Successfully sent status code: 201
{
"message": "Valid Message"
}FAILURE OUTCOME
Failure outcome status code: 404
{
"message": "missing parameter:toNumber"
}Example Error Response
These messages will appear in the JSON response key of “message”.
| missing parameter:toNumber |
| missing parameter:fromNumber |
| missing parameter:body |
| missing parameter:APIKey |
| Invalid KEY |
| Invalid DID |
| Invalid To Number |
| Invalid Message |
| Opt-Out |
| Invalid Key/Company Combination |