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, billing, token QR codes, and plan details.

Base URL

https://staging.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://staging.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://staging.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 Keywords Devices 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": "juan@example.com"
  }
}

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, plan, and subscription metadata.

2 endpoints

GET/api/v5/account

Retrieve wallet, plan, keyword usage, and active API token details.

Auth

JSON Response Example

{
  "wallets": {
    "balance": 150.00
  },
  "planDetails": {
    "name": "Basic",
    "limit": 1000
  },
  "total_keyword_used": 3,
  "authToken": "1|abc123..."
}

GET/api/v5/account/plan/details

List active subscription plans.

Auth

JSON Response Example

[
  {
    "id": 1,
    "name": "Basic",
    "amount": 999,
    "is_active": 1
  }
]

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
}

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

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."
}

Billing

Billing invoices and payment history.

1 endpoints

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": "Basic Plan",
      "amount": 999.00,
      "status": "paid",
      "paid_at": "2026-05-09T10:00:00.000000Z"
    }
  ],
  "current_page": 1,
  "last_page": 2
}