SMS

Voicebip sends and receives SMS through persistent SMPP v3.4 sessions to all four Nigerian MNO SMSCs — MTN, Glo, Airtel, and 9mobile. Messages are routed by number prefix with automatic failover.

Sending an SMS

Send an outbound SMS via the unified messages endpoint:

$
curl -X POST "https://api.voicebip.com/v1/messages" \
>
  -H "Authorization: Bearer pk_live_your_key" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "agent_id": "agt_PAEZ_njcfm2kycpjs",
>
    "channel": "sms",
>
    "from_number": "+2348031000001",
>
    "to_number": "+2348061234567",
>
    "body": "Your verification code is 482910. It expires in 10 minutes."
>
  }'

Response:

1
{
2
  "message_id": "msg_k7Tz9mWvXp3nR",
3
  "channel": "sms",
4
  "status": "queued",
5
  "from_number": "+2348031000001",
6
  "to_number": "+2348061234567",
7
  "segments": 1,
8
  "created_at": "2026-04-09T12:00:00Z"
9
}

The message is queued for delivery via the appropriate MNO SMPP session. You receive delivery status updates through webhooks.

Receiving Inbound SMS

When a user sends an SMS to one of your provisioned +234 numbers, Voicebip delivers a message.received webhook to your endpoint:

1
{
2
  "event_id": "evt_Rj4kLm8nQ",
3
  "event_type": "message.received",
4
  "channel": "sms",
5
  "agent_id": "agt_PAEZ_njcfm2kycpjs",
6
  "number": "+2348031000001",
7
  "from": "+2348061234567",
8
  "timestamp": "2026-04-09T12:05:00Z",
9
  "payload": {
10
    "message_id": "msg_Xp7nR3kTz9mW",
11
    "body": "What is my account balance?",
12
    "encoding": "GSM-7"
13
  }
14
}

Your agent can process the inbound message and reply using the same POST /v1/messages endpoint.

Auto-Segmentation

SMS messages are automatically split into segments when they exceed character limits:

The segments field in the response tells you how many segments the message was split into. Each segment is billed independently.

Delivery Receipts

Voicebip requests delivery receipts (DLRs) from the MNO for every outbound message. When the MNO confirms delivery, a message.dlr webhook is sent:

1
{
2
  "event_id": "evt_Np2xVb5kQ",
3
  "event_type": "message.dlr",
4
  "channel": "sms",
5
  "agent_id": "agt_PAEZ_njcfm2kycpjs",
6
  "timestamp": "2026-04-09T12:00:03Z",
7
  "payload": {
8
    "message_id": "msg_k7Tz9mWvXp3nR",
9
    "status": "delivered",
10
    "to_number": "+2348061234567",
11
    "delivered_at": "2026-04-09T12:00:02Z"
12
  }
13
}

Possible DLR statuses: delivered, failed, rejected, expired.

STOP Opt-Out Handling

Voicebip includes built-in opt-out keyword handling to comply with messaging regulations. When a recipient replies with any of these keywords, they are automatically opted out:

• STOP
• UNSUBSCRIBE
• CANCEL
• END
• QUIT

Keyword matching is case-insensitive. Once a number is opted out, any attempt to send an SMS to that number returns a 422 error:

1
{
2
  "error_code": "OPT_OUT_ENFORCED",
3
  "message": "Recipient +2348061234567 has opted out of SMS from this agent.",
4
  "request_id": "req_abc123",
5
  "documentation_url": "https://docs.voicebip.com/errors/OPT_OUT_ENFORCED"
6
}

Opt-out state is tracked per agent. A recipient can opt back in by sending START or SUBSCRIBE.

MNO Routing

Voicebip routes each SMS to the correct MNO SMSC based on the recipient’s phone number prefix:

If the prefix is unrecognized, the message is routed to MTN as the default carrier.

Failover

If the primary MNO SMSC is unreachable, Voicebip fails over through the chain: MTN -> Glo -> Airtel -> 9mobile. Failover is automatic and transparent — the API response is the same regardless of which SMSC delivers the message.

SMPP Infrastructure

Voicebip maintains one persistent SMPP v3.4 session per MNO SMSC. Key details:

• Keep-alive: ENQUIRE_LINK every 30 seconds
• Throughput: bounded by MNO-allocated TPS per session
• Connection recovery: automatic reconnect with exponential backoff on session loss

Sandbox Testing

Use a pk_test_ API key to send SMS in sandbox mode. Sandbox messages are not delivered to real MNO networks — synthetic NATS events simulate the full lifecycle (queued, delivered). Billing is NGN 0.

Sandbox numbers: +234800000xxxx (test mobile virtual).

$
curl -X POST "https://api.voicebip.com/v1/messages" \
>
  -H "Authorization: Bearer pk_test_your_key" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "agent_id": "agt_PAEZ_njcfm2kycpjs",
>
    "channel": "sms",
>
    "from_number": "+2348000001000",
>
    "to_number": "+2348000002000",
>
    "body": "Hello from sandbox"
>
  }'