DevelopersCOSMOS SMS API
Abstract
This section describes how to integrate Cosmos HTTP API into your business.
How to integrate COSMOS SMS API
You can use COSMOS SMS API to send to COSMOS.mobi users. The workflow for sending outbound messages using SMS API is:
- Create a request to send an SMS and check a response.
- If you have a webhook, check Delivery Status that we send via callback.
Each request you make using the COSMOS SMS API returns a:
- Response - the status and cost of your request to COSMOS API in JSON.
- Delivery Status - if you have set a webhook endpoint, COSMOS API forwards this delivery receipt to it. COSMOS.mobi return a Delivery Status to explain the status of your message.
By default, your COSMOS Developer Account is configured for REST. If you already use SMPP and want to use COSMOS.mobi, see how to configure SMPP Access
How to create a request to send an SMS
POST
/sms/
Resource URL
https://api.cosmos.mobi/v1.0/sms/Resource Information
| Request/Response formats | JSON |
| Encoding | UTF-8 |
Headers
| Content-Type | application/json |
| Accept | application/json |
Request Parameters
api_key required | Your API key. Data type: String Example value: "1EdZEH7484krjSQt1zg782SPHjiU5xgvk5" |
api_secret required | Your API Secret key. Data type: String Example value: "L3tj45j45934534kKcrwrRaoGPwR8ZNTtHPSgTGRwy57x" |
to required | The virtual phone number of the COSMOS.mobi user. Data type: String Pattern: ^0[0-9]14$ Example value: "033334445566770" |
from required | The name of your sender address. Data type: String Example value: "Company Name 123" |
text required | A message from the sender. Data type: String Length: <180 (Unicode <70) Example value: "Hello world!" |
callback optional | A callback URL that will receive an asynchronous response from COSMOS SMS API. Data type: String Example value: "http://your-site.com/response?param1=value1" |
Parameters Example:
{
"api_key": "1EdZEH7484krjSQt1zg782SPHjiU5xgvk5",
"api_secret": "L3tj45j45934534kKcrwrRaoGPwR8ZNTtHPSgTGRwy57x",
"to": "033334445566770",
"from": "Company Name 123",
"text": "Hello world!",
"callback": "http://your-site.com/response?param1=value1"
}How to handle a response
Response Success
status | A code that explains if your message was sent. Possible value is: HTTP Code 200: "ok" - the message was successfully sent.Data type: String Example value: "ok" |
message_id | The COSMOS.mobi ID for this message. Data type: String Example value: "Az_42415-252521" |
price | How much it costs in US dollar to send this message. Data type: Float Example value: 0.0 |
Response Success Example:
{
"status": "ok",
"message_id": "Az_42415-252521",
"price": 0.0
}Response Error
status | A code that explains why the error appears. Possible values are: HTTP Code 400: "invalid_to" - the invalid virtual phone number format of COSMOS.mobi user."invalid_from" - the invalid "from" parameter. "invalid_text" - the message could not be sent because the message was incorrect or too large. "invalid_callback" - the invalid "callback" parameter. "invalid_json" - the invalid JSON format. "failed" - there is no phone number or user set his phone to "inactive" state. "spam" - we often apply restrictions that block messages following different criteria. "blacklist" - you tried to send a message to a blacklisted phone number. That is, the user has already sent a STOP opt-out message and no longer wishes to receive messages from you. HTTP Code 401: "unauthorized" - invalid credentials.HTTP Code 408: "timeout" - you have either bad connection or request was lasted to long.HTTP Code 413: "large_request" - your request was larger than 4kb.HTTP Code 500: "internal_error" - there is a problem from our side. To resolve this issue email us at support@cosmos.mobi.Data type: String Example value: "unauthorized" |
Response Error Example:
{
"status": "unauthorized"
}Delivery Status
The Delivery Status Callback is sent using a POST HTTP request to your webhook endpoint.
Delivery Status Parameters
status | A code that explains where the message is in the delivery process. Possible values are: Data type: String Example value: "delivered" |
to | The parameter "to" you set in your request. Data type: String Example value: "033334445566770" |
message_id | The COSMOS.mobi ID for this message. Data type: String Example value: "Az_42415-252521" |
price | How much it costs in US dollar to send this message. Data type: Float Example value: 0.0 |
message_timestamp | The time at UTC+00:00 when COSMOS.mobi started to push this Delivery Status to your webhook endpoint. Data type: String Pattern: YYYY-MM-DD HH:MM:SS Example value: "2012-04-05 09:22:57" |
Delivery Status Parameters Example:
{
"status": "delivered",
"to": "033334445566770",
"message_id": "Az_42415-252521",
"price": 0.0,
"message_timestamp": "2016-04-05 09:22:57"
}