Public API Documentation

Build with MSG4wrd.io API v5

Use the v5 API for authentication, inbound SMS, outbound queues, contacts, keyword webhooks, GSM modem devices, SMS campaigns, monitoring, top-ups, account limits, billing, and token QR codes.

All authenticated portal features are available to every account by default. Wallet credits and account limits govern usage.

Base URL

https://api.msg4wrd.io

Authentication

Call /api/login, then send protected requests with a Bearer token.

Message Status

0pending

1sending

2success

3failed

Response Format

All endpoints return JSON. Validation failures include a message and may include an errors map.

POST /api/v5/send

Send SMS Status Flow

Send requests are documented separately because the API queues an outbound message first, then the sender workflow moves it through status codes.

Queue a message

curl -X POST "https://api.msg4wrd.io/api/v5/send?mobile=09171234567&message=Hello%20from%20MSG4wrd&local=0&priority=0" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Accept: application/json"

Save the returned sent.id. That ID is the same value used for resend when the outbound message later fails.

Resend failed message

curl -X POST "https://api.msg4wrd.io/api/v5/inbound/message/125/resend" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Accept: application/json"

1Read messages from GET /api/v5/inbound or GET /api/v5/inbound/thread/{mobile}.
2Find an outbound message where is_inbound is 0 and status is 3.
3Call POST /api/v5/inbound/message/{id}/resend using that message ID.
4A successful resend resets the same message to status 0 pending and returns the updated sent object.

0Pending

The API accepted the request, charged the wallet, created the outbound SMS row, and returned the message ID in sent.id.

Store sent.id. The gateway/device worker picks up pending outbound messages for delivery.

1Sending

The message is actively being processed by the sender workflow.

Do not resend yet. Continue reading the thread or inbound list until the status moves to success or failed.

2Success

The outbound SMS was marked as delivered/sent by the processing workflow.

No resend action is needed.

3Failed

The outbound SMS failed and is eligible for API resend if it belongs to the authenticated account.

Call POST /api/v5/inbound/message/{id}/resend with the failed outbound message ID.

Endpoint Catalog

API v5 Routes

Open portal docs

Base Account Send SMS Inbound Contacts SMS Campaigns Keywords Devices Sender Numbers Billing

Base

Authentication bootstrap and session/token management.

4 endpoints

POST/api/login

Authenticate with email/password and receive a bearer token.

Public

ParameterTypeRequiredDescription

Parameteremail

Typestring

Requiredrequired

DescriptionRegistered email address.

Parameterpassword

Typestring

Requiredrequired

DescriptionAccount password.

JSON Response Example

{
  "token": "1|abc123...",
  "user": {
    "id": 1,
    "firstname": "Juan",
    "lastname": "Dela Cruz",
    "email": "[email protected]"
  }
}

POST/api/v5/logout

End the current session without revoking the persisted API token.

Auth

JSON Response Example

204 No Content

POST/api/v5/tokens/create

Regenerate the account API token and invalidate previous tokens.

Auth

JSON Response Example

{
  "token": "2|xyz789..."
}

GET/api/v5/tokens/qr-code

Return a QR code data URI for the active API token.

Auth

JSON Response Example

{
  "qr_code": "data:image/svg+xml;base64,PHN2Zy...",
  "mime_type": "image/svg+xml"
}

Account

Account wallet, usage, and device and outbound SMS limit metadata.

1 endpoints

GET/api/v5/account

Retrieve wallet, account limits and usage, keyword usage, and active API token details.

Auth

JSON Response Example

{
  "wallets": {
    "balance": 150.00
  },
  "limits": {
    "device_limit": 1,
    "devices_used": 0,
    "devices_remaining": 1,
    "sms_daily_limit": 200,
    "sms_sent_today": 0,
    "sms_remaining_today": 200,
    "sms_monthly_limit": 3000,
    "sms_sent_this_month": 0,
    "sms_remaining_this_month": 3000
  },
  "total_keyword_used": 3,
  "authToken": "1|abc123...",
  "realtime_channel": "account-realtime-channel"
}

Send SMS

Outbound SMS queueing, status tracking, and failed-message resend behavior.

1 endpoints

POST/api/v5/send

Queue an outbound SMS message using query parameters.

Auth

ParameterTypeRequiredDescription

Parametermobile

Typestring

Requiredrequired

DescriptionRecipient mobile number query parameter.

Parametermessage

Typestring

Requiredrequired

DescriptionSMS body query parameter, maximum 160 characters.

Parameterlocal

Typeinteger

Requiredoptional

DescriptionCountry routing flag query parameter. Use 0 for PH (default) or 1 for US.

Parametersendername

Typestring

Requiredoptional

DescriptionSender name query parameter. Defaults to default; custom sender names follow the same queue behavior as /api/v2/sms.

Parameterpriority

Typeinteger

Requiredoptional

DescriptionPriority query parameter. Use 0 for normal priority (default) or 1 for high priority.

JSON Response Example

{
  "message": "Message queued successfully.",
  "charged": 1,
  "sent": {
    "id": 124,
    "mobile": "09171234567",
    "normalized_mobile": "+639171234567",
    "content": "Hello",
    "sender": "default",
    "is_inbound": 0,
    "local": 0,
    "priority": 0,
    "status": 0,
    "created_at": "2026-05-09T10:01:00.000000Z"
  }
}

Inbound

SMS conversations, replies, failed-message retries, and device ingestion.

5 endpoints

GET/api/v5/inbound

List paginated SMS conversations across inbound messages and outbound replies.

Auth

ParameterTypeRequiredDescription

Parametersearch

Typestring

Requiredoptional

DescriptionSearch by mobile number, message content, or sender.

Parameterpage

Typeinteger

Requiredoptional

DescriptionPage number. Defaults to 1.

JSON Response Example

{
  "data": [
    {
      "id": 123,
      "from_mobile": "09171234567",
      "normalized_mobile": "+639171234567",
      "contact_name": "Juan Dela Cruz",
      "contact_mobile": "09171234567",
      "content": "Hello",
      "is_inbound": 1,
      "status": 2,
      "received_at": "2026-05-09T10:00:00.000000Z"
    }
  ],
  "current_page": 1,
  "last_page": 3,
  "realtime_channel": "account-realtime-channel"
}

GET/api/v5/inbound/thread/{mobile}

Retrieve a full SMS thread by mobile number.

Auth

ParameterTypeRequiredDescription

Parametermobile

Typestring

Requiredrequired

DescriptionMobile number in the URL path.

JSON Response Example

{
  "mobile": "+639171234567",
  "variants": ["09171234567", "+639171234567"],
  "messages": [
    {
      "id": 123,
      "mobile": "09171234567",
      "normalized_mobile": "+639171234567",
      "content": "Hello",
      "sender": "default",
      "is_inbound": 0,
      "status": 0,
      "created_at": "2026-05-09T10:00:00.000000Z"
    }
  ]
}

POST/api/v5/inbound/reply

Send a manual reply to an inbound thread target.

Auth

ParameterTypeRequiredDescription

Parametermobile

Typestring

Requiredrequired

DescriptionRecipient mobile number or normalized thread mobile.

Parametermessage

Typestring

Requiredrequired

DescriptionSMS body, maximum 160 characters.

JSON Response Example

{
  "message": "Reply sent successfully.",
  "sent": {
    "id": 125,
    "mobile": "09171234567",
    "normalized_mobile": "+639171234567",
    "content": "Reply text",
    "sender": "default",
    "is_inbound": 0,
    "status": 0,
    "created_at": "2026-05-09T10:02:00.000000Z"
  }
}

POST/api/v5/inbound/message/{id}/resend

Reset a failed outbound SMS message back to pending.

Auth

ParameterTypeRequiredDescription

Parameterid

Typeinteger

Requiredrequired

DescriptionFailed outbound SMS message ID in the URL path.

JSON Response Example

{
  "message": "Message queued for resend.",
  "sent": {
    "id": 125,
    "mobile": "09171234567",
    "normalized_mobile": "+639171234567",
    "content": "Reply text",
    "sender": "default",
    "is_inbound": 0,
    "status": 0,
    "created_at": "2026-05-09T10:02:00.000000Z"
  }
}

POST/api/v5/inbound

Store and forward an inbound SMS from a registered device integration.

Auth

ParameterTypeRequiredDescription

Parameterdevice_uid

Typestring

Requiredrequired

DescriptionRegistered active device identifier.

Parametermobile

Typestring

Requiredrequired

DescriptionSender mobile number.

Parametermessage

Typestring

Requiredrequired

DescriptionInbound SMS body.

Parameterlocal

Typeinteger

Requiredoptional

DescriptionCountry routing flag. Use 0 for PH (default) or 1 for US.

JSON Response Example

{
  "status": 200,
  "message": "success"
}

Contacts

Saved SMS contacts used by inbound lists and manual sends.

4 endpoints

GET/api/v5/contacts

List saved SMS contacts.

Auth

JSON Response Example

{
  "data": [
    {
      "id": 1,
      "name": "Juan Dela Cruz",
      "mobile": "09171234567",
      "created_at": "2026-05-09T10:00:00.000000Z",
      "updated_at": "2026-05-09T10:00:00.000000Z"
    }
  ]
}

POST/api/v5/contacts

Create a saved SMS contact.

Auth

ParameterTypeRequiredDescription

Parametername

Typestring

Requiredrequired

DescriptionContact display name, maximum 100 characters.

Parametermobile

Typestring

Requiredrequired

DescriptionContact mobile number, maximum 30 characters and unique per user.

JSON Response Example

{
  "message": "Contact added successfully.",
  "contact": {
    "id": 1,
    "name": "Juan Dela Cruz",
    "mobile": "09171234567",
    "created_at": "2026-05-09T10:00:00.000000Z",
    "updated_at": "2026-05-09T10:00:00.000000Z"
  }
}

PUT/api/v5/contacts/{id}

Update a saved SMS contact.

Auth

ParameterTypeRequiredDescription

Parameterid

Typeinteger

Requiredrequired

DescriptionContact record ID in the URL path.

Parametername

Typestring

Requiredrequired

DescriptionContact display name, maximum 100 characters.

Parametermobile

Typestring

Requiredrequired

DescriptionContact mobile number, unique per user.

JSON Response Example

{
  "message": "Contact updated successfully.",
  "contact": {
    "id": 1,
    "name": "Juan Dela Cruz",
    "mobile": "09171234567",
    "created_at": "2026-05-09T10:00:00.000000Z",
    "updated_at": "2026-05-09T10:05:00.000000Z"
  }
}

DELETE/api/v5/contacts/{id}

Delete a saved SMS contact.

Auth

ParameterTypeRequiredDescription

Parameterid

Typeinteger

Requiredrequired

DescriptionContact record ID in the URL path.

JSON Response Example

204 No Content

SMS Campaigns

Recipient-file parsing, sample templates, draft creation, delivery reporting, reuse, and queued sending.

7 endpoints

POST/api/v5/campaigns/parse

Parse an XLSX, CSV, or TXT recipient file into a validation preview.

Auth

ParameterTypeRequiredDescription

Parameterfile

Typefile

Requiredrequired

DescriptionRecipient file up to 10 MB.

GET/api/v5/campaigns/template/{type}

Download a basic, company, or unique-message sample template.

Auth

ParameterTypeRequiredDescription

Parametertype

Typestring

Requiredrequired

DescriptionLayout: basic, company, or unique.

Parameterformat

Typestring

Requiredoptional

DescriptionQuery value: xlsx, csv, or txt.

GET/api/v5/campaigns

List campaigns plus aggregate recipient and delivery totals.

Auth

ParameterTypeRequiredDescription

Parameterpage

Typeinteger

Requiredoptional

DescriptionPage number.

POST/api/v5/campaigns

Save a campaign draft without spending credits or sending messages.

Auth

ParameterTypeRequiredDescription

Parametername

Typestring

Requiredrequired

DescriptionCampaign name.

Parametermessages

Typestring[]

Requiredrequired

DescriptionOne to 10 messages, each up to 160 characters.

Parameterrecipients

Typeobject[]

Requiredrequired

DescriptionParsed recipients with mobile and optional variables.

Parametersource_filename

Typestring

Requiredoptional

DescriptionOriginal recipient filename.

GET/api/v5/campaigns/{id}

Retrieve campaign totals, cost estimate, wallet balance, and recipient delivery statuses.

Auth

ParameterTypeRequiredDescription

Parameterid

Typeinteger

Requiredrequired

DescriptionCampaign ID.

Parameterpage

Typeinteger

Requiredoptional

DescriptionRecipient page number.

Parameterstatus

Typestring

Requiredoptional

DescriptionOptional recipient status filter.

GET/api/v5/campaigns/{id}/duplicate

Load a previous campaign into the Copy and Use composer workflow.

Auth

ParameterTypeRequiredDescription

Parameterid

Typeinteger

Requiredrequired

DescriptionCampaign ID.

POST/api/v5/campaigns/{id}/send

Queue a draft after checking wallet credits and daily/monthly outbound limits.

Auth

ParameterTypeRequiredDescription

Parameterid

Typeinteger

Requiredrequired

DescriptionDraft campaign ID.

Keywords

Keyword routing, webhook assignment, devices, and linked mobile numbers.

4 endpoints

GET/api/v5/keywords-devices

Retrieve keywords, mobile devices, and linked mobile numbers.

Auth

JSON Response Example

{
  "keywords": [
    {
      "id": 1,
      "keyword": "PAYMENT",
      "webhook": "https://example.com/webhook",
      "status": true
    }
  ],
  "devices": [
    {
      "id": 1,
      "name": "Main GSM Modem",
      "device_id": "DEVICE-001",
      "mobile": "09171234567",
      "status": true
    }
  ]
}

POST/api/v5/keyword/create

Create a keyword and webhook configuration.

Auth

ParameterTypeRequiredDescription

Parameterkeyword

Typestring

Requiredrequired

DescriptionUnique keyword. Letters, numbers, underscores, and dashes are accepted.

Parameterwebhook

Typeurl

Requiredrequired

DescriptionHTTPS endpoint that receives transaction payloads.

Parameterdevice_id

Typeinteger

Requiredoptional

DescriptionEnabled mobile device record ID to tag.

Parameterewallet_channel

Typeinteger

Requiredoptional

Description1 for SMS Command Only, 2 for all commands.

Parameteris_default_webhook

Typeboolean

Requiredoptional

DescriptionUse as fallback for unmatched transactions.

Parameterdefault_webhook

Typeboolean

Requiredoptional

DescriptionLegacy alias for is_default_webhook.

Parameterstatus

Typeboolean

Requiredoptional

DescriptionEnable or disable this keyword.

Parametermobile_app

Typeboolean

Requiredoptional

DescriptionLegacy alias used to enable the keyword when status is omitted.

JSON Response Example

{
  "success": true,
  "message": "Keyword created"
}

PUT/api/v5/keyword/{id}

Update an existing keyword.

Auth

ParameterTypeRequiredDescription

Parameterid

Typeinteger

Requiredrequired

DescriptionKeyword record ID in the URL path.

Parameterkeyword

Typestring

Requiredrequired

DescriptionUnique keyword. Letters, numbers, underscores, and dashes are accepted.

Parameterwebhook

Typeurl

Requiredrequired

DescriptionHTTPS endpoint that receives transaction payloads.

Parameterdevice_id

Typeinteger

Requiredoptional

DescriptionEnabled mobile device record ID to tag.

Parameterewallet_channel

Typeinteger

Requiredoptional

Description1 for SMS Command Only, 2 for all commands.

Parameteris_default_webhook

Typeboolean

Requiredoptional

DescriptionUse as fallback for unmatched transactions.

Parameterdefault_webhook

Typeboolean

Requiredoptional

DescriptionLegacy alias for is_default_webhook.

Parameterstatus

Typeboolean

Requiredoptional

DescriptionEnable or disable this keyword.

Parametermobile_app

Typeboolean

Requiredoptional

DescriptionLegacy alias used to enable the keyword when status is omitted.

JSON Response Example

{
  "success": true,
  "message": "Keyword updated."
}

DELETE/api/v5/keyword/{id}

Delete an existing keyword.

Auth

ParameterTypeRequiredDescription

Parameterid

Typeinteger

Requiredrequired

DescriptionKeyword record ID in the URL path.

JSON Response Example

{
  "success": true,
  "message": "Keyword deleted."
}

Devices

GSM modem device registration and management.

3 endpoints

POST/api/v5/device/create

Auth

ParameterTypeRequiredDescription

Parameterid

Typeinteger

Requiredoptional

DescriptionExisting device ID. Include to update through create endpoint.

Parameteris_update

Typeboolean

Requiredoptional

DescriptionLegacy update flag.

Parametername

Typestring

Requiredrequired

DescriptionDisplay name for the device.

Parameterdevice_id

Typestring

Requiredrequired

DescriptionUnique hardware identifier.

Parametermobile

Typestring

Requiredrequired

DescriptionSIM card mobile number installed in the device.

Parameteris_autoreply_to_sender

Typeboolean

Requiredoptional

DescriptionAutomatically reply to inbound SMS senders.

Parameteris_msg4wrd

Typeboolean

Requiredoptional

DescriptionUse MSG4wrd as the outbound sender.

Parameterstatus

Typeboolean

Requiredoptional

DescriptionEnable or disable this device. Defaults to enabled.

JSON Response Example

{
  "success": true,
  "message": "Device registered"
}

PUT/api/v5/device/{id}

Update a registered GSM modem device.

Auth

ParameterTypeRequiredDescription

Parameterid

Typeinteger

Requiredrequired

DescriptionDevice record ID in the URL path.

Parametername

Typestring

Requiredrequired

DescriptionDisplay name for the device.

Parameterdevice_id

Typestring

Requiredrequired

DescriptionUnique hardware identifier.

Parametermobile

Typestring

Requiredrequired

DescriptionSIM card mobile number installed in the device.

Parameteris_autoreply_to_sender

Typeboolean

Requiredoptional

DescriptionAutomatically reply to inbound SMS senders.

Parameteris_msg4wrd

Typeboolean

Requiredoptional

DescriptionUse MSG4wrd as the outbound sender.

Parameterstatus

Typeboolean

Requiredoptional

DescriptionEnable or disable this device.

JSON Response Example

{
  "success": true,
  "message": "Device updated."
}

DELETE/api/v5/device/{id}

Delete a registered GSM modem device.

Auth

ParameterTypeRequiredDescription

Parameterid

Typeinteger

Requiredrequired

DescriptionDevice record ID in the URL path.

JSON Response Example

{
  "success": true,
  "message": "Device deleted."
}

Sender Numbers

Blocked sender-number management for Philippine and US numbers.

2 endpoints

POST/api/v5/sender-number/create

Add a number to the account’s blocked-sender list.

Auth

ParameterTypeRequiredDescription

Parametermobile

Typestring

Requiredrequired

DescriptionInternational PH or US mobile number.

DELETE/api/v5/sender-number/{id}

Delete a blocked sender number owned by the account.

Auth

ParameterTypeRequiredDescription

Parameterid

Typeinteger

Requiredrequired

DescriptionSender-number record ID.

Billing

Top-up offers, promos, limit add-ons, one-time checkout, payment history, and invoices.

9 endpoints

GET/api/v5/credit-packages

List active credit top-ups, promos, and account-limit add-ons.

Public

GET/api/v5/payments

List one-time purchase and legacy payment history.

Auth

ParameterTypeRequiredDescription

Parameterpage

Typeinteger

Requiredoptional

DescriptionPage number.

GET/api/v5/payments/{id}/proof

Download the authenticated account’s own manual payment proof image.

Auth

ParameterTypeRequiredDescription

Parameterid

Typeinteger

Requiredrequired

DescriptionPayment transaction ID.

GET/api/v5/payments/gateway-settings

Read enabled payment gateways and public checkout configuration.

Public

GET/api/v5/payments/gateway-settings/{gateway}/qr

Download the configured public QR image for GCash or Maya.

Public

ParameterTypeRequiredDescription

Parametergateway

Typestring

Requiredrequired

Descriptiongcash or maya.

POST/api/v5/checkout/paypal/order

Create a PayPal order for an active offer.

Auth

ParameterTypeRequiredDescription

Parametercredit_package_id

Typeinteger

Requiredrequired

DescriptionActive offer ID.

POST/api/v5/checkout/paypal/order/{txn}/capture

Capture a PayPal order and fulfill credits and limit increments once.

Auth

ParameterTypeRequiredDescription

Parametertxn

Typeinteger

Requiredrequired

DescriptionPayment transaction ID.

POST/api/v5/checkout/manual

Submit GCash or Maya payment details and proof for verification.

Auth

ParameterTypeRequiredDescription

Parametercredit_package_id

Typeinteger

Requiredrequired

DescriptionActive offer ID.

Parametergateway

Typestring

Requiredrequired

Descriptiongcash or maya.

Parameterreference_number

Typestring

Requiredrequired

DescriptionPayment reference number.

Parameterproof

Typefile

Requiredrequired

DescriptionPayment proof image.

GET/api/v5/billing

List billing invoices and payment history.

Auth

ParameterTypeRequiredDescription

Parameterpage

Typeinteger

Requiredoptional

DescriptionPage number. Defaults to 1.

JSON Response Example

{
  "data": [
    {
      "id": 1,
      "description": "Credit top-up",
      "amount": 999.00,
      "status": "paid",
      "paid_at": "2026-05-09T10:00:00.000000Z"
    }
  ],
  "current_page": 1,
  "last_page": 2
}