API Documentation

Overview

The TextBetter Messaging APIs allow customers to send and receive SMS and MMS messages using either:

• v1 — Querystring (Legacy)
• v2 — JSON (Current)

Both outgoing and incoming messaging are supported. New integrations should use v2 whenever possible.

Environments

Production

Production access is enabled by default.

Base URLs

• Outgoing v1: https://api.textbetter.com
• Outgoing v2 (SMS & MMS): https://api2.textbetter.com
• Incoming v1 / v2: Customer-provided webhook URL

Sandbox / Staging

Sandbox (staging) environments are available upon request.

• Provisioned on demand
• Separate credentials issued
• Message delivery behavior may differ from production

Phone Number Format

Phone numbers must be provided as an 11-digit numeric string based on the E.164 standard.

• Country code (1 digit, US only)
• Area code
• Subscriber number
• Digits only
• No + prefix
• No spaces, dashes, or parentheses

For reference:
E.164 is the international telephone numbering plan that gives each device on the Public Switched Telephone Network (PSTN) a globally unique number.

Valid Example

15551230001

Invalid Example

+15551230001
(555) 123-0001
555-123-0001

Authentication

Outgoing Messaging API (v2 — JSON)

Two credentials are required on every request.

Function Access Code

Customer API Key (APIKey)

Outgoing Messaging API (v1 — Querystring)

Outgoing Messaging API (v2 — JSON)

EndPoint

POST https://api2.textbetter.com/api/SendOutgoingMessages?code={FUNCTION_CODE}

Headers

Content-Type: application/json

Send SMS (v2)

Parameters

Example request body

{
  "fromNumber": "15551230001",
  "toNumber": ["12003004001"],
  "body": "Hello World",
  "APIKey": "YOUR_CUSTOMER_API_KEY"
}

Example cURL request

The following example demonstrates sending an SMS message using the v2 JSON API.

curl --location --globoff 'https://api2.textbetter.com/api/SendOutgoingMessages?code={FUNCTION_CODE}' \
--header 'Content-Type: application/json' \
--data '{
  "fromNumber": "15551230001",
  "toNumber": ["12003004001"],
  "body": "Hello World",
  "APIKey": "YOUR_CUSTOMER_API_KEY"
}'

Send MMS (v2)

Parameters

{
  "fromNumber": "15551230001",
  "toNumber": ["12003004001"],
  "body": "Here is the image",
  "APIKey": "YOUR_CUSTOMER_API_KEY",
  "filenames": ["image.jpg"],
  "contentTypes": ["image/jpeg"],
  "images": ["BASE64_ENCODED_IMAGE"]
}

Example cURL request

The following example demonstrates sending an MMS message using the v2 JSON API.

curl --location --globoff 'https://api2.textbetter.com/api/SendOutgoingMessages?code={FUNCTION_CODE}' \
--header 'Content-Type: application/json' \
--data '{
  "fromNumber": "15551230001",
  "toNumber": ["12003004001"],
  "body": "Here is the image",
  "APIKey": "YOUR_CUSTOMER_API_KEY",
  "filenames": ["image.jpg"],
  "contentTypes": ["image/jpeg"],
  "images": ["BASE64_ENCODED_IMAGE"]
}'

Media rules

Media fields must be arrays of equal length
Each index represents a single attachment
Media must be Base64 encoded

Responses (v2)

Response fields

message: Human-readable status message for debugging and logging purposes only. Do not rely on this value for application logic.
RecordID: TextBetter internal message record identifier.
CarrierID: Carrier-assigned message identifier (when available).

Success — 201 Created

{
  "message": "Valid Message",
  "CarrierID": "17685045592347zt2zp3ohfr5mbmo",
  "RecordID": "68041609"
}

Error — 400 Bad Request

{
  "message": "Invalid Company/KEY/DID combination",
  "CarrierID": "0",
  "RecordID": "0"
}

Outgoing Messaging API (v1 — Querystring)

Endpoint

GET https://api.textbetter.com/SendTexts.aspx

Parameters

Example request

https://api.textbetter.com/SendTexts.aspx?KEY=YOUR_KEY&DID=15551230001&ToNumber=12003004001&Message=Hello%20World

Example cURL request

The following example demonstrates sending an SMS message using the v1 Querystring API.

curl 'https://api.textbetter.com/SendTexts.aspx?KEY=YOUR_KEY&DID=15551230001&ToNumber=12003004001&Message=Hello%20World'

Response

Important:
v1 always returns HTTP 200 OK. Treat the request as successful only when the response body equals Success!.

Incoming Messaging API (v2 — JSON)

Incoming messages are delivered to a customer-provided endpoint.

• Method: POST
• Content-Type: application/json

Parameters

Incoming SMS

{
  "id": "123",
  "to": "15551230001",
  "from": "12003004001",
  "timestamp": 1666798041,
  "type": "SMS",
  "text": "Hello World"
}

Incoming MMS

{
  "id": "124",
  "to": "15551230001",
  "from": "12003004001",
  "timestamp": 1666798123,
  "type": "MMS",
  "text": "",
  "images": [
    {
      "Base64": "BASE64_ENCODED_IMAGE",
      "type": "image/png"
    }
  ]
}

Incoming Messaging API (v1 — Querystring)

Incoming v1 messages are delivered via querystring parameters.

• Method: GET

Parameters

Example Request

https://your-endpoint.example?From=12003004001&To=15551230001&Message=Hi

Version Guidance