Textbelt

https://docs.textbelt.com/
Admin
Textbelt is a simple SMS API designed for developers to easily send and receive text messages and...
Tokens:7,994
Snippets:100
Trust Score:8.2
Update:2 months ago
Show doc for...
Tokens:
Raw
### Quota Response Example

Source: https://docs.textbelt.com/other-api-endpoints.md

Example of the JSON response returned by the quota endpoint.

```json
{"success": true, "quotaRemaining": 98}
```

--------------------------------

### Query documentation via HTTP GET

Source: https://docs.textbelt.com/llms.txt

Perform an HTTP GET request to the documentation index with an ask parameter to receive a direct answer and relevant excerpts.

```http
GET https://docs.textbelt.com/master.md?ask=<question>&goal=<end_goal>
```

--------------------------------

### API Response Examples

Source: https://docs.textbelt.com/master.md

Examples of JSON responses returned by the /text endpoint for successful, quota-limited, and incomplete requests.

```javascript
{"success": true, "quotaRemaining": 40, "textId": 12345}
```

```javascript
{"success": false, "quotaRemaining": 0, "error": "Out of quota"}
```

```javascript
{"success": false, "error": "Incomplete request"}
```

--------------------------------

### API Response Examples

Source: https://docs.textbelt.com/otp-mobile-verification.md

Examples of successful and failed JSON responses from the OTP generation endpoint.

```json
{"success": true, "textId": "1234", "quotaRemaining": 70, "otp": "672383"}
```

```json
{"success": false, "quotaRemaining": 0, "otp": ""}
```

--------------------------------

### SMS Status Response Example

Source: https://docs.textbelt.com/other-api-endpoints.md

Example of the JSON response returned by the status endpoint.

```json
{"status": "DELIVERED"}
```

--------------------------------

### Send SMS with Custom Webhook Data

Source: https://docs.textbelt.com/master.md

Example of sending an SMS with the optional webhookData field.

```bash
curl -X POST https://textbelt.com/text \
     --data-urlencode phone='5555555555' \
     --data-urlencode message='Hello?' \
     -d replyWebhookUrl='https://my.site/api/handleSmsReply' \
     -d webhookData='my custom data'
     -d key=textbelt
```

--------------------------------

### OTP Verification Response Examples

Source: https://docs.textbelt.com/otp-mobile-verification.md

JSON responses indicating whether the submitted OTP is valid or invalid.

```json
{"success": true, "isValidOtp": true}
```

```json
{"success": true, "isValidOtp": false}
```

--------------------------------

### Check API Credit Balance

Source: https://docs.textbelt.com/other-api-endpoints.md

Retrieve the remaining quota for an API key by sending a GET request.

```bash
curl https://textbelt.com/quota/abc123
```

--------------------------------

### Generate OTP via API

Source: https://docs.textbelt.com/otp-mobile-verification.md

Basic examples for sending an OTP request using various programming languages and tools.

```bash
curl -X POST https://textbelt.com/otp/generate \
     --data-urlencode phone='5555555555' \
     --data-urlencode userid='myuser@site.com' \
     -d key=example_otp_key
```

```python
import requests

resp = requests.post('https://textbelt.com/otp/generate', {
  'phone': '5555555555',
  'userid': 'myuser@site.com',
  'key': 'example_otp_key',
})
print(resp.json())
```

```ruby
require 'net/http'
require 'uri'

uri = URI.parse("https://textbelt.com/otp/generate")
Net::HTTP.post_form(uri, {
  :phone => '5555555555',
  :userid => 'myuser@site.com',
  :key => 'example_otp_key',
})
```

```javascript
const request = require('request');
request('https://textbelt.com/otp/generate', {
  body: {
    phone: '5555555555',
    userid: 'myuser@site.com',
    key: 'example_otp_key',
  },
})
```

```javascript
fetch('https://textbelt.com/text', {
  method: 'post',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    phone: '5555555555',
    userid: 'myuser@site.com',
    key: 'example_otp_key',
  }),
}).then(response => {
  return response.json();
}).then(data => {
  console.log(data);
});
```

```php
$ch = curl_init('https://textbelt.com/otp/generate');
$data = array(
  'phone' => '5555555555',
  'userid' => 'myuser@site.com',
  'key' => 'example_otp_key',
);

curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);
```

```csharp
using System;
using System.Collections.Specialized;
using System.Net;

using (WebClient client = new WebClient())
{
  byte[] response = client.UploadValues("http://textbelt.com/text", new NameValueCollection() {
    { "phone", "5555555555" },
    { "userid", "myuser@site.com" },
    { "key", "example_otp_key" },
  });

  string result = System.Text.Encoding.UTF8.GetString(response);
}
```

```java
final NameValuePair[] data = {
    new BasicNameValuePair("phone", "5555555555"),
    new BasicNameValuePair("userid", "myuser@site.com"),
    new BasicNameValuePair("key", "example_otp_key")
};
HttpClient httpClient = HttpClients.createMinimal();
HttpPost httpPost = new HttpPost("https://textbelt.com/otp/generate");
httpPost.setEntity(new UrlEncodedFormEntity(Arrays.asList(data)));
HttpResponse httpResponse = httpClient.execute(httpPost);

String responseString = EntityUtils.toString(httpResponse.getEntity());
JSONObject response = new JSONObject(responseString);
```

```go
import (
  "net/http"
  "net/url"
)

func main() {
  values := url.Values{
    "phone": {"5555555555"},
    "userid": {"myuser@site.com"},
    "key": {"example_otp_key"},
  }

  http.PostForm("https://textbelt.com/text", values)
}
```

```powershell
$body = @{
  "phone"="5555555555"
  "userid"="myuser@site.com"
  "key"="example_otp_key"
}
$submit = Invoke-WebRequest -Uri https://textbelt.com/text -Body $body -Method Post
```

--------------------------------

### Customize OTP with Optional Parameters

Source: https://docs.textbelt.com/otp-mobile-verification.md

Example of sending an OTP request with additional customization parameters like message content, lifetime, and length.

```bash
curl -X POST https://textbelt.com/otp/generate \
     --data-urlencode phone='5557727420' \
     --data-urlencode userid='myuser@site.com' \
     --data-urlencode message='Nuclear launch code: $OTP! Use it to login.' \
     -d lifetime=120 \
     -d length=4 \
     -d key=example_otp_key
```

--------------------------------

### GET /otp/verify

Source: https://docs.textbelt.com/otp-mobile-verification.md

Verifies that the OTP code entered by a user matches the one associated with their user ID.

```APIDOC
## GET /otp/verify

### Description
Verifies that the OTP code entered by a user is valid for the specified user ID.

### Method
GET

### Endpoint
https://textbelt.com/otp/verify

### Parameters
#### Query Parameters
- **otp** (string) - Required - The code entered by the user.
- **userid** (string) - Required - The ID of the user.
- **key** (string) - Required - Your Textbelt API key.

### Response
#### Success Response (200)
- **success** (boolean) - Whether the request was successfully received and processed.
- **isValidOtp** (boolean) - Whether the OTP is correct for the given userid.

#### Response Example
{
  "success": true,
  "isValidOtp": true
}
```

--------------------------------

### GET /master.md

Source: https://docs.textbelt.com/llms.txt

Queries the documentation index to receive a direct answer to a specific question, along with relevant excerpts and sources.

```APIDOC
## GET https://docs.textbelt.com/master.md

### Description
Perform an HTTP GET request on the documentation index to ask a specific question and optionally provide a broader goal for tailored results.

### Method
GET

### Endpoint
https://docs.textbelt.com/master.md

### Parameters
#### Query Parameters
- **ask** (string) - Required - The immediate, specific question to ask.
- **goal** (string) - Optional - The broader end goal to help tailor the response.

### Request Example
GET https://docs.textbelt.com/master.md?ask=How do I send an SMS?&goal=Integrate SMS into my app

### Response
#### Success Response (200)
- **answer** (string) - A direct answer to the question.
- **excerpts** (array) - Relevant excerpts from the documentation.
- **sources** (array) - Links to the source documentation pages.
```

--------------------------------

### GET /quota/:key

Source: https://docs.textbelt.com/other-api-endpoints.md

Retrieves the remaining SMS credit quota for a given API key.

```APIDOC
## GET /quota/:key

### Description
Checks the remaining SMS credit balance associated with an API key.

### Method
GET

### Endpoint
https://textbelt.com/quota/:key

### Parameters
#### Path Parameters
- **key** (string) - Required - The API key to check.

### Response
#### Success Response (200)
- **success** (boolean) - Whether the key lookup was successful.
- **quotaRemaining** (number) - The amount of SMS credit remaining.

### Response Example
{
  "success": true,
  "quotaRemaining": 98
}
```

--------------------------------

### Webhook Payload Example

Source: https://docs.textbelt.com/master.md

The structure of the JSON payload sent to your webhook endpoint when an SMS reply is received.

```javascript
{
  "textId": "123456",
  "fromNumber": "+1555123456",
  "text": "Here is my reply"
}
```

--------------------------------

### Send SMS with Reply Webhook

Source: https://docs.textbelt.com/master.md

Example of sending an SMS message with a configured reply webhook URL using cURL.

```bash
curl -X POST https://textbelt.com/text \
     --data-urlencode phone='5555555555' \
     --data-urlencode message='Hello?' \
     -d replyWebhookUrl='https://my.site/api/handleSmsReply' \
     -d key=textbelt
```

--------------------------------

### Verify OTP via cURL

Source: https://docs.textbelt.com/otp-mobile-verification.md

Perform an HTTP GET request to the /otp/verify endpoint to validate a user-provided code.

```bash
user_entered_code=12345
userid=myuser@site.com
key=example_otp_key

curl "https://textbelt.com/otp/verify?otp=${user_entered_code}&userid=${userid}&key=${key}"
```

--------------------------------

### GET /status/:textId

Source: https://docs.textbelt.com/other-api-endpoints.md

Retrieves the delivery status of a specific SMS message using its textId.

```APIDOC
## GET /status/:textId

### Description
Checks the delivery status of a message given its textId.

### Method
GET

### Endpoint
https://textbelt.com/status/:textId

### Parameters
#### Path Parameters
- **textId** (string) - Required - The unique identifier for the sent message.

### Response
#### Success Response (200)
- **status** (string) - The delivery status of the message (DELIVERED, SENT, SENDING, FAILED, or UNKNOWN).

### Response Example
{
  "status": "DELIVERED"
}
```

--------------------------------

### Check SMS Delivery Status

Source: https://docs.textbelt.com/other-api-endpoints.md

Retrieve the delivery status of a message by sending a GET request with the textId.

```bash
curl https://textbelt.com/status/12345
```

--------------------------------

### Send SMS via Node.js

Source: https://docs.textbelt.com/master.md

Demonstrates sending requests using either the request or axios libraries.

```javascript
// Using request
const request = require('request');
request.post('https://textbelt.com/text', {
  form: {
    phone: '5555555555',
    message: 'Hello world',
    key: 'textbelt',
  },
}, (err, httpResponse, body) => {
  console.log(JSON.parse(body));
});

// Using axios
const axios = require('axios');
axios.post('https://textbelt.com/text', {
  phone: '5555555555',
  message: 'Hello world',
  key: 'textbelt',
}).then(response => {
  console.log(response.data);
})
```

--------------------------------

### POST /otp/generate

Source: https://docs.textbelt.com/otp-mobile-verification.md

Creates a one-time code and sends it to the specified phone number.

```APIDOC
## POST /otp/generate

### Description
Creates a one-time code and sends it to the user's phone.

### Method
POST

### Endpoint
https://textbelt.com/otp/generate

### Parameters
#### Request Body
- **phone** (string) - Required - A phone number. Use E.164 format for non-U.S. numbers.
- **userid** (string) - Required - An id that is unique to your user.
- **key** (string) - Required - Your Textbelt API key.
- **message** (string) - Optional - The content of your SMS. Replaces the default message. Use the $OTP variable to include the OTP.
- **lifetime** (integer) - Optional - Determines how many seconds the OTP is valid for. Defaults to 180.
- **length** (integer) - Optional - The number of digits in your OTP. Defaults to 6.
```

--------------------------------

### Chain Command with SMS Notification

Source: https://docs.textbelt.com/guides/sending-sms-from-command-line.md

Executes a long-running command and sends an SMS notification upon successful completion.

```bash
./my_long_running_command.sh && text 5551234567
```

--------------------------------

### Send SMS via Go

Source: https://docs.textbelt.com/master.md

Uses the net/http package to post form values.

```go
import (
  "net/http"
  "net/url"
)

func main() {
  values := url.Values{
    "phone": {"5555555555"},
    "message": {"Hello world"},
    "key": {"textbelt"},
  }

  http.PostForm("https://textbelt.com/text", values)
}
```

--------------------------------

### Send SMS via PHP

Source: https://docs.textbelt.com/master.md

Uses cURL to initialize and execute a POST request.

```php
$ch = curl_init('https://textbelt.com/text');
$data = array(
  'phone' => '5555555555',
  'message' => 'Hello world',
  'key' => 'textbelt',
);

curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);
```

--------------------------------

### Send SMS via Java

Source: https://docs.textbelt.com/master.md

Uses Apache HttpComponents to execute an HTTP POST request.

```java
final NameValuePair[] data = {
    new BasicNameValuePair("phone", "5555555555"),
    new BasicNameValuePair("message", "Hello world"),
    new BasicNameValuePair("key", "textbelt")
};
HttpClient httpClient = HttpClients.createMinimal();
HttpPost httpPost = new HttpPost("https://textbelt.com/text");
httpPost.setEntity(new UrlEncodedFormEntity(Arrays.asList(data)));
HttpResponse httpResponse = httpClient.execute(httpPost);

String responseString = EntityUtils.toString(httpResponse.getEntity());
JSONObject response = new JSONObject(responseString);
```

--------------------------------

### Send SMS via Email using Mutt

Source: https://docs.textbelt.com/guides/sending-sms-from-command-line.md

Sends a text message through an email gateway using the mutt command-line mail client.

```bash
echo "my message" | mutt -s "my subject" abc@gmail.com
```

--------------------------------

### Send SMS via C#

Source: https://docs.textbelt.com/master.md

Uses WebClient to upload form values to the API.

```csharp
using System;
using System.Collections.Specialized;
using System.Net;

using (WebClient client = new WebClient())
{
  byte[] response = client.UploadValues("http://textbelt.com/text", new NameValueCollection() {
    { "phone", "5555555555" },
    { "message", "Hello world" },
    { "key", "textbelt" },
  });

  string result = System.Text.Encoding.UTF8.GetString(response);
}
```

--------------------------------

### Create a Shell Alias for Textbelt

Source: https://docs.textbelt.com/guides/sending-sms-from-command-line.md

Defines a shell function in .bashrc to simplify sending SMS messages via the Textbelt API.

```bash
text() {
  curl https://textbelt.com/text --data-urlencode number="$1" --data-urlencode "message=$2" -d key=textbelt
} 
```

--------------------------------

### Send SMS via Python

Source: https://docs.textbelt.com/master.md

Uses the requests library to send a POST request.

```python
import requests

resp = requests.post('https://textbelt.com/text', {
  'phone': '5555555555',
  'message': 'Hello world',
  'key': 'textbelt',
})
print(resp.json())
```

--------------------------------

### POST /otp/generate

Source: https://docs.textbelt.com/otp-mobile-verification.md

Generates and sends a one-time verification code to the specified phone number.

```APIDOC
## POST /otp/generate

### Description
Generates a one-time verification code and sends it to the provided phone number. The response includes the generated OTP and a textId for tracking.

### Method
POST

### Endpoint
https://textbelt.com/otp/generate

### Parameters
#### Request Body
- **phone** (string) - Required - The recipient's phone number.
- **userid** (string) - Required - A unique identifier for the user.
- **key** (string) - Required - Your API key.
- **message** (string) - Optional - Custom message template containing $OTP.
- **lifetime** (integer) - Optional - Time in seconds the OTP is valid.
- **length** (integer) - Optional - Length of the generated OTP.

### Response
#### Success Response (200)
- **success** (boolean) - Whether the OTP was successfully sent.
- **textId** (string) - The ID of the sent text message.
- **quotaRemaining** (integer) - Remaining credits on the API key.
- **otp** (string) - The generated one-time verification code.

#### Response Example
{
  "success": true,
  "textId": "1234",
  "quotaRemaining": 70,
  "otp": "672383"
}
```

--------------------------------

### Verify Webhook Signature

Source: https://docs.textbelt.com/master.md

Functions to verify the X-textbelt-signature header using an HMAC SHA-256 hash.

```javascript
const crypto = require("crypto");

function verify(apiKey, timestamp, requestSignature, requestPayload) {
  const mySignature = crypto
    .createHmac("sha256", apiKey)
    .update(timestamp + requestPayload)
    .digest("hex");
    
  return crypto.timingSafeEqual(
    Buffer.from(requestSignature),
    Buffer.from(mySignature)
  );
}
```

```python
import hmac
import hashlib

def verify(api_key, timestamp, request_signature, request_payload):
    my_signature = hmac.new(api_key.encode('utf-8'), (timestamp + request_payload).encode('utf-8'), hashlib.sha256).hexdigest()
    return hmac.compare_digest(request_signature, my_signature)
```

--------------------------------

### Send SMS via Browser JavaScript

Source: https://docs.textbelt.com/master.md

Uses the Fetch API to send a JSON-formatted POST request.

```javascript
fetch('https://textbelt.com/text', {
  method: 'post',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    phone: '5555555555',
    message: 'Hello world',
    key: 'textbelt',
  }),
}).then(response => {
  return response.json();
}).then(data => {
  console.log(data);
});
```

--------------------------------

### Send SMS via PowerShell

Source: https://docs.textbelt.com/master.md

Uses Invoke-WebRequest to send a POST request with a body hash.

```bash
$body = @{
  "phone"="5555555555"
  "message"="Hello World"
  "key"="textbelt"
}
$submit = Invoke-WebRequest -Uri https://textbelt.com/text -Body $body -Method Post
```

--------------------------------

### POST /text

Source: https://docs.textbelt.com/master.md

Sends an SMS message to a specified phone number.

```APIDOC
## POST /text

### Description
Sends an SMS message to the provided phone number.

### Method
POST

### Endpoint
https://textbelt.com/text

### Request Body
- **phone** (string) - Required - The recipient's phone number.
- **message** (string) - Required - The content of the SMS message.
- **key** (string) - Required - The API key for authentication.

### Request Example
{
  "phone": "5555555555",
  "message": "Hello world",
  "key": "textbelt"
}
```

--------------------------------

### Send SMS via Textbelt API

Source: https://docs.textbelt.com/guides/sending-sms-from-command-line.md

Uses curl to send an SMS message through the Textbelt API.

```bash
curl -X POST https://textbelt.com/text \
       --data-urlencode phone='5557727420' \
       --data-urlencode message='Hello world' \
       -d key=textbelt
```

--------------------------------

### Send SMS via Ruby

Source: https://docs.textbelt.com/master.md

Uses Net::HTTP to post form data to the API endpoint.

```ruby
require 'net/http'
require 'uri'

uri = URI.parse("https://textbelt.com/text")
Net::HTTP.post_form(uri, {
  :phone => '5555555555',
  :message => 'Hello world',
  :key => 'textbelt',
})
```

--------------------------------

### POST /text

Source: https://docs.textbelt.com/master.md

Sends an SMS message to a specified phone number. Supports optional reply webhooks and custom data.

```APIDOC
## POST /text

### Description
Sends an SMS message. To test without deducting credits, append "_test" to your API key.

### Method
POST

### Endpoint
https://textbelt.com/text

### Parameters
#### Request Body
- **phone** (string) - Required - The recipient's phone number.
- **message** (string) - Required - The content of the SMS.
- **key** (string) - Required - Your API key.
- **replyWebhookUrl** (string) - Optional - URL to receive SMS replies via POST.
- **webhookData** (string) - Optional - Custom data (max 100 chars) passed back in the webhook request.

### Response
#### Success Response (200)
- **success** (boolean) - Whether the message was successfully sent.
- **quotaRemaining** (number) - Credits remaining on the key.
- **textId** (number) - ID of the sent message (only if success=true).

#### Error Response
- **success** (boolean) - false
- **error** (string) - Description of the problem.
```

--------------------------------

### Webhook Response with Custom Data

Source: https://docs.textbelt.com/master.md

The resulting webhook payload when custom data is included in the request.

```javascript
{
  "textId": "123456",
  "fromNumber": "+1555123456",
  "text": "Here is my reply"
  "data": "my custom data"
}
```

--------------------------------

### POST https://textbelt.com/text

Source: https://docs.textbelt.com/master.md

Sends an SMS message to a specified phone number using an API key.

```APIDOC
## POST https://textbelt.com/text

### Description
Sends an SMS message to the specified phone number. This endpoint is designed to be simple and does not require special libraries.

### Method
POST

### Endpoint
https://textbelt.com/text

### Parameters
#### Request Body
- **phone** (string) - Required - A phone number. Use 10-digit format for U.S./Canada or E.164 format for international numbers.
- **message** (string) - Required - The content of the SMS.
- **key** (string) - Required - Your API key (use 'textbelt' for a free message).
- **sender** (string) - Optional - The name of the business or organization for regulatory purposes.
```

--------------------------------

### POST https://textbelt.com/text

Source: https://docs.textbelt.com/

Sends an SMS message to a specified phone number.

```APIDOC
## POST https://textbelt.com/text

### Description
Sends an SMS message to the provided phone number using the specified API key.

### Method
POST

### Endpoint
https://textbelt.com/text

### Parameters
#### Request Body
- **phone** (string) - Required - A phone number. Use 10-digit format for U.S./Canada or E.164 format for international numbers.
- **message** (string) - Required - The content of the SMS message.
- **key** (string) - Required - Your API key (use 'textbelt' for free messages).
- **sender** (string) - Optional - The name of the business or organization for regulatory purposes.

### Request Example
{
  "phone": "5555555555",
  "message": "Hello world",
  "key": "textbelt"
}
```
Tokens:
Raw