Message

A message represents an SMS sent or received through the VoIPBIN platform, enabling programmatic text communication with phone numbers worldwide.

API Reference: Message endpoints

Overview

Note

AI Context

Complexity: Low
Cost: Chargeable (per message segment sent)
Async: Yes. POST /messages returns immediately with status sending. Poll GET /messages/{id} or use webhooks to track delivery status changes.

VoIPBIN’s Message API enables you to send and receive SMS (Short Message Service) and MMS (Multimedia Messaging Service) globally. Whether you need to send notifications, alerts, verification codes, or marketing messages, the Message API provides a reliable solution for text-based communication.

With the Message API you can:

Send SMS messages to phone numbers worldwide
Send MMS messages with images, videos, and other media
Receive inbound messages via webhooks
Track message delivery status
Integrate messaging into automated workflows

How Messaging Works

When you send a message, VoIPBIN routes it through carrier networks to reach the recipient’s mobile device.

Message Architecture

+----------+        +----------------+        +-----------+
| Your App |--API-->|    VoIPBIN     |--SMPP->|  Carrier  |
+----------+        |  Message Hub   |        |  Network  |
                    +----------------+        +-----+-----+
                           |                        |
                           |                        v
                    +------+------+           +-----------+
                    |   Webhook   |           | Recipient |
                    |  (status)   |           |  Device   |
                    +-------------+           +-----------+

Key Components

Message Hub: Routes messages to appropriate carriers based on destination
Carrier Network: Delivers messages to recipient devices (SMS/MMS)
Webhooks: Notify your application of delivery status and inbound messages

Message Types

Message Lifecycle

Every message moves through a predictable set of states from sending to delivery.

Outbound Message States

POST /messages
       |
       v
+------------+
|  sending   |
+-----+------+
      |
      v
+------------+     delivery failed     +------------+
|   sent     |------------------------>|   failed   |
+-----+------+                         +------------+
      |
      | carrier accepted
      v
+------------+     delivery failed     +------------+
| delivered  |------------------------>|   failed   |
+------------+                         +------------+

State Descriptions

State	What’s happening
sending	Message is being processed and routed to carrier
sent	Message has been sent to carrier network
delivered	Carrier confirmed delivery to recipient device
failed	Message could not be delivered (invalid number, carrier error)

Inbound Message Flow

Sender Device        Carrier Network           VoIPBIN              Your App
     |                     |                      |                    |
     | SMS/MMS             |                      |                    |
     +------------------->|                      |                    |
     |                     | Forward message      |                    |
     |                     +-------------------->|                    |
     |                     |                      |                    |
     |                     |                      | message_received   |
     |                     |                      | webhook            |
     |                     |                      +------------------->|
     |                     |                      |                    |

Sending Messages

VoIPBIN provides multiple ways to send messages based on your use case.

Method 1: Via API

Send messages directly using the REST API.

Your App                    VoIPBIN                    Recipient
   |                           |                           |
   | POST /messages            |                           |
   +-------------------------->|                           |
   |                           | Route to carrier          |
   |                           +-------------------------->|
   |  message_id               |                           |
   |  status: "sending"        |                           |
   |<--------------------------+                           |
   |                           |                           |
   | Webhook: status update    |   SMS delivered           |
   |<--------------------------+-------------------------->|
   |                           |                           |

Note

AI Implementation Hint

All phone numbers must be in E.164 format: start with +, followed by country code and number, no dashes or spaces. For example, +15551234567 (US) or +821012345678 (Korea). The source must be a number you own, obtainable via GET /numbers. Unicode characters (emoji, non-Latin scripts) reduce the per-segment character limit from 160 to 70.

Send SMS Example:

$ curl -X POST 'https://api.voipbin.net/v1.0/messages?token=<token>' \
    --header 'Content-Type: application/json' \
    --data '{
        "source": "+15551234567",
        "destinations": [
            {
                "type": "tel",
                "target": "+15559876543"
            }
        ],
        "text": "Your verification code is 123456"
    }'

Send MMS Example:

$ curl -X POST 'https://api.voipbin.net/v1.0/messages?token=<token>' \
    --header 'Content-Type: application/json' \
    --data '{
        "source": "+15551234567",
        "destinations": [
            {
                "type": "tel",
                "target": "+15559876543"
            }
        ],
        "text": "Check out this image!",
        "medias": [
            {
                "type": "image/jpeg",
                "url": "https://example.com/image.jpg"
            }
        ]
    }'

Method 2: Via Flow Action

Send messages as part of an automated flow.

{
    "type": "message_send",
    "option": {
        "source": "+15551234567",
        "text": "Your appointment is confirmed for tomorrow at 2pm."
    }
}

When to Use Each Method

Method	Best for
API	Direct integration, transactional messages, custom logic
Flow Action	Automated responses, call-triggered SMS, workflow integration

Receiving Messages

VoIPBIN delivers inbound messages to your application via webhooks.

Webhook Delivery

VoIPBIN                           Your App
    |                                 |
    | POST /your-webhook-endpoint     |
    | {message_received event}        |
    +-------------------------------->|
    |                                 |
    |            200 OK               |
    |<--------------------------------+
    |                                 |

Inbound Message Webhook Payload:

{
    "type": "message_received",
    "data": {
        "id": "msg-abc-123",
        "source": {
            "type": "tel",
            "target": "+15559876543"
        },
        "destination": {
            "type": "tel",
            "target": "+15551234567"
        },
        "text": "Hello, I need help with my order",
        "direction": "inbound",
        "tm_create": "2024-01-15T10:30:00Z"
    }
}

Status Update Webhook:

{
    "type": "message_updated",
    "data": {
        "id": "msg-abc-123",
        "status": "delivered",
        "tm_update": "2024-01-15T10:30:05Z"
    }
}

Message Formatting

Understanding message limits and encoding helps optimize delivery.

SMS Character Limits

Encoding	Single Message	Concatenated (per segment)
GSM-7 (standard)	160 characters	153 characters
Unicode (emoji, non-Latin)	70 characters	67 characters

Long Message Handling

Your message: "This is a longer message that exceeds 160 characters..."
                                    |
                                    v
+-------------------------------------------------------------------+
| VoIPBIN automatically splits into segments:                       |
|                                                                   |
| Segment 1: "This is a longer message that exceeds 160 char..."   |
| Segment 2: "...acters and continues here with more content..."   |
| Segment 3: "...and finally ends here."                           |
|                                                                   |
| Recipient's phone reassembles into single message                 |
+-------------------------------------------------------------------+

MMS Media Types

Media Type	Supported Formats
Images	JPEG, PNG, GIF
Video	MP4, 3GP
Audio	MP3, WAV
Documents	PDF, vCard

Common Scenarios

Scenario 1: Verification Code

Send a one-time password for user verification.

User requests login
     |
     v
+--------------------+
| Generate OTP: 1234 |
+--------+-----------+
         |
         v
POST /messages
"Your code is 1234"
         |
         v
User receives SMS
Enters code to verify

Scenario 2: Appointment Reminder

Send automated reminders before appointments.

24 hours before appointment
          |
          v
+--------------------------+
| Trigger: scheduled job   |
+------------+-------------+
             |
             v
POST /messages
"Reminder: Appointment tomorrow at 2pm"
             |
             v
Customer receives SMS

Scenario 3: Two-Way Conversation

Enable customers to reply to messages.

Your App                VoIPBIN                  Customer
    |                      |                        |
    | "Order shipped!"     |                        |
    +--------------------->+----------------------->|
    |                      |                        |
    |                      |    "When arrives?"     |
    |<---------------------+<-----------------------+
    |  message_received    |                        |
    |                      |                        |
    | "Expected Friday"    |                        |
    +--------------------->+----------------------->|
    |                      |                        |

Scenario 4: MMS Marketing

Send promotional messages with images.

+------------------------------------------+
| POST /messages                           |
| {                                        |
|   "text": "Summer sale! 50% off!",       |
|   "medias": [                            |
|     {"url": "https://.../promo.jpg"}     |
|   ]                                      |
| }                                        |
+------------------------------------------+
                  |
                  v
Customer receives image + text message

Best Practices

1. Sender ID Selection

Use a phone number your customers recognize
For transactional messages, use a consistent sender
Check country-specific sender ID regulations

2. Message Content

Keep messages concise and actionable
Include opt-out instructions for marketing messages
Avoid URL shorteners that may trigger spam filters

3. Rate Limiting

Respect carrier rate limits to avoid throttling
Spread bulk messages over time
Monitor for carrier feedback signals

4. Compliance

Obtain consent before sending marketing messages
Honor opt-out requests promptly
Follow local regulations (TCPA, GDPR, etc.)

Troubleshooting

Message Not Delivered

Symptom	Solution
Status stays “sending”	Check carrier connectivity; verify destination number format (+E.164)
Status “failed”	Check error code; common issues: invalid number, carrier rejection, insufficient credit
Delivered but not received	Recipient’s phone may be off or out of range; carrier may delay delivery

Inbound Messages Not Received

Symptom	Solution
No webhook calls	Verify webhook URL is configured and publicly accessible
Webhook returns error	Ensure endpoint returns 200 OK within 5 seconds
Missing messages	Check webhook logs; implement idempotency using message ID

Character Encoding Issues

Symptom	Solution
Message truncated	Check for Unicode characters; they reduce character limit to 70
Strange characters	Ensure UTF-8 encoding in API requests

Message

Message struct

{
    "id": "<string>",
    "type": "sms",
    "source": {
        "type": "tel",
        "target": "+15551234567",
        "target_name": "",
        "name": "",
        "detail": ""
    },
    "targets": [
        {
            "destination": {
                "type": "tel",
                "target": "+15559876543",
                "target_name": "",
                "name": "",
                "detail": ""
            },
            "status": "sent",
            "parts": 1,
            "tm_update": "2022-03-13 15:11:06.497184184"
        }
    ],
    "text": "Hello, this is test message.",
    "direction": "outbound",
    "tm_create": "2022-03-13 15:11:05.235717",
    "tm_update": "2022-03-13 15:11:06.497278",
    "tm_delete": "9999-01-01 00:00:00.000000"
}

id (UUID): The message’s unique identifier. Returned when creating via POST /messages or listing via GET /messages.
type (enum string): The message type. See Type.
source (Object): Source address info. See Address.
targets (Array of Object): List of delivery targets with per-destination status. See Target.
text (String): The message body text content.
direction (enum string): Whether the message is inbound or outbound. See Direction.
tm_create (string, ISO 8601): Timestamp when the message was created.
tm_update (string, ISO 8601): Timestamp of the last status update.
tm_delete (string, ISO 8601): Timestamp of deletion (soft delete).

Note

AI Implementation Hint

Timestamps set to 9999-01-01 00:00:00.000000 indicate the event has not yet occurred. For example, tm_delete with this value means the message has not been deleted.

Target

Target struct

{
    "destination": {
        "type": "tel",
        "target": "+15559876543",
        "target_name": "",
        "name": "",
        "detail": ""
    },
    "status": "sent",
    "parts": 1,
    "tm_update": "2022-03-13 15:11:06.497184184"
}

destination (Object): Destination address info. See Address.
status (enum string): Delivery status for this specific destination (e.g., sending, sent, delivered, failed).
parts (Integer): Number of message segments. Long SMS messages are split into multiple parts (153 characters each for GSM-7 encoding).
tm_update (string, ISO 8601): Timestamp of the last status update for this target.

Type

Message’s type.

Direction

Message’s direction.

Direction	Description
inbound	Incoming message received from an external sender to your VoIPBIN number. Delivered to your application via webhook.
outbound	Outgoing message sent from your application via the VoIPBIN API to an external recipient.

Tutorial

Before sending messages, you need:

An authentication token. Obtain one via POST /auth/login or use an access key from GET /accesskeys.
A source phone number in E.164 format (e.g., +15551234567). This must be a number you own. Obtain your numbers via GET /numbers.
A destination phone number in E.164 format (e.g., +15559876543).

Note

AI Implementation Hint

Sending messages incurs charges per message segment. All phone numbers must be in E.164 format: start with +, followed by country code and number, no dashes or spaces. The source and destinations fields use the Address format with type set to tel.

Send a message

$ curl --location --request POST 'https://api.voipbin.net/v1.0/messages?token=<YOUR_AUTH_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "source": {
        "type": "tel",
        "target": "+15559876543"
    },
    "destinations": [
        {
            "type": "tel",
            "target":"+31616818985"
        }
    ],
    "text": "hello, this is test message."
}'

Get list of messages

$ curl --location --request GET 'https://api.voipbin.net/v1.0/messages?token=<YOUR_AUTH_TOKEN>&page_size=10'

{
"result": [
    {
        "id": "a5d2114a-8e84-48cd-8bb2-c406eeb08cd1",
        "type": "sms",
        "source": {
            "type": "tel",
            "target": "+15551234567",
            "target_name": "",
            "name": "",
            "detail": ""
        },
        "targets": [
            {
                "destination": {
                    "type": "tel",
                    "target": "+15559876543",
                    "target_name": "",
                    "name": "",
                    "detail": ""
                },
                "status": "sent",
                "parts": 1,
                "tm_update": "2022-03-13 15:11:06.497184184"
            }
        ],
        "text": "Hello, this is test message.",
        "direction": "outbound",
        "tm_create": "2022-03-13 15:11:05.235717",
        "tm_update": "2022-03-13 15:11:06.497278",
        "tm_delete": "9999-01-01 00:00:00.000000"
    },
    ...
]

Message

Overview

How Messaging Works

Message Lifecycle

Sending Messages

Receiving Messages

Message Formatting

Common Scenarios

Best Practices

Troubleshooting

Related Documentation

Message

Message

Target

Type

Direction

Tutorial

Send a message

Get list of messages