Message

Overview

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           |
   |<--------------------------+-------------------------->|
   |                           |                           |

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: Message’s ID.
type: Message’s type. See detail here.
source: Source address info. See detail here.
targets: List of targets. See detail here.
destinations: List of destination addresses info. See detail here.
targets: List of targets. See detail here.
text: Message’s text.
direction: Message’s direction. See detail here.

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: Destination address info. See detail here.
status: Message’s status for this destination.
parts: Number of parted message.

Type

Message’s type.

Type	Description
sms	SMS.

Direction

Message’s direction.

Type	Description
inbound	Incoming message.
outbound	Outgoing message.

Tutorial

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