Inbound Message API

The Inbound Message API allows organizations to send messages through various communication channels (e.g., SMS). This API processes and publishes messages, ensuring they are sent correctly and validated against the organization's credentials.

API Base URL: https://api.ubiqio.com/

Authentication

All API requests must be authenticated using a Bearer token. Obtain a JWT token by authenticating with your clientId and clientSecret.

Get a JWT Token

Endpoint: POST /mvapi/auth/token

Request Body (JSON)

Field	Type	Required	Description
`clientId`	string	✅	Your unique account identifier
`clientSecret`	string	✅	Your secret key associated with the account

Example Request

curl -X POST https://api.ubiqio.com/mvapi/auth/token \
-H "Content-Type: application/json" \
-d '{
  "clientId": "AKab29...",
  "clientSecret": "2q5HAEY..."
}'

Success Response

{
  "token": "eyJr......"
}

Error Response

{
  "error": "Check your account key and secret"
}

Once obtained, include the token in the Authorization header:

Authorization: Bearer <JWT token>

Endpoints

POST /send

Send a message through a specified communication channel. This endpoint validates the message, checks the organization's credentials, and publishes the message.

URL: https://api.ubiqio.com/mvapi/message/send
Method: POST
Auth: Bearer token required
Content-Type: application/json

Request Body (JSON)

Field	Type	Required	Description
`accountId`	string	✅	Unique identifier for the account
`toNumber`	string	✅	Recipient phone number
`message`	string	✅	Content of the message
`templateId`	string	✅	Template ID for the message
`priority`	int	✅	Priority level. Set to `0` for high priority
`channel`	string	✅	`SMS` or `MMS`
`imageUrl`	string	—	Image URL (MMS only)
`caption`	string	—	Image caption (MMS only)
`clientRef`	string	—	Client reference for additional identification

Example Request

curl -X POST https://api.ubiqio.com/mvapi/message/send \
-H "Authorization: Bearer <JWT token>" \
-H "Content-Type: application/json" \
-d '{
  "accountId": "6f0a2bde-b73a-41a9-8143-7cb53e484e1e",
  "toNumber": "+14083539000",
  "message": "Hello, this is a test message!",
  "templateId": "1eeb416f-dbdd-40e0-baba-d2f8224d8413",
  "priority": 1,
  "channel": "SMS"
}'

Success Response

{
  "message_uuid": "e13b76e5-cf9d-4e6d-a787-9aab36e34c64"
}

Validation Error Response

{
  "error": "Phone number format is incorrect: +12345",
  "Message ID": "5c5a02f9-4b93-40d1-a44b-dae88a1b72a6"
}

Unauthorized Error Response

{
  "Unauthorized": "Invalid Authorization Header",
  "Message ID": "e13b76e5-cf9d-4e6d-a787-9aab36e34c64"
}

Response Codes

Code	Status	Description
`200`	OK	Message was successfully processed
`400`	Bad Request	Invalid parameters (e.g., malformed phone numbers or UUIDs)
`401`	Unauthorized	Bearer token was missing or invalid
`500`	Internal Server Error	Unexpected error during processing

SendMessageRequest Object

Field	Type	Required	Description
`accountId`	string	✅	Unique identifier for the account
`toNumber`	string	✅	Recipient phone number
`message`	string	✅	Content of the message
`templateId`	string	✅	Template ID for the message
`priority`	int	—	Priority level. `0` = high priority
`channel`	string	✅	`SMS` or `MMS`
`statusCallbackUrl`	string	—	URL for status callbacks
`retries`	int	—	Retry count (internal use only)
`imageUrl`	string	—	Image URL (MMS only)
`caption`	string	—	Image caption (MMS only)
`clientRef`	string	—	Client reference

Webhooks

Webhooks are sent to the URL specified in the template for both status updates and inbound messages.

Status Webhook

{
  "updateDTTM": 1775348523774,
  "mvId": "94f7f0fb-2b79-4964-af2a-31adcd76faa5",
  "vendorMessageId": "add3e431-032a-4913-a726-7a9f65db9264",
  "vendorFormat": {
    "client_ref": "Testing",
    "usage": "VonageMessageResponse.Usage(currency=USD, price=0.00995000)",
    "channel": "SMS",
    "from": "18335644693",
    "message_uuid": "add3e431-032a-4913-a726-7a9f65db9264",
    "to": "14083142771",
    "insertDTTM": 1775348523554,
    "error": "VonageMessageResponse.Error(type=null, title=202, detail=null, instance=null)",
    "status": "Testing"
  },
  "insertDTTM": 1775348521114,
  "vendorAccountId": "",
  "status": "Testing"
}

Inbound Webhook

{
  "price": "0.0059",
  "mvId": "a7f843df-6205-4d21-81f6-e0f1f9c18a17",
  "vendorMessageId": "6a86faa0-0f4e-42c0-a122-ef29384d245a",
  "from": "14085551001",
  "to": "18331235062",
  "vendorFormat": {
    "usage": { "price": 0.0059, "currency": "EUR" },
    "origin": { "network_code": "310004" },
    "channel": "sms",
    "sms": { "num_messages": 1 },
    "message_type": "text",
    "from": "14085551001",
    "message_uuid": "6a86faa0-0f4e-42c0-a122-ef29384d245a",
    "to": "18331235062",
    "text": "Thanks!",
    "context_status": "none",
    "timestamp": "2026-04-05T00:26:00Z"
  },
  "insertDTTM": 1775348760879,
  "body": "Thanks!",
  "status": "inbound-message"
}

Best Practices

Secure your JWT Tokens — Never expose Bearer tokens in public repositories or client-side code.
Validate Request Parameters — Ensure all required fields (accountId, channel, toNumber) are properly formatted before sending.
Idempotency — Send each request only once per message, or implement your own idempotency mechanism to prevent duplicate processing.