SMS API
SMPP API

COSMOS 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:

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 formatsJSON
EncodingUTF-8

Headers

Content-Typeapplication/json
Acceptapplication/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:

"delivered" - the message was successfully delivered.

"not_delivered" - the message was failed to deliver. To resolve this issue email us at support@cosmos.mobi.

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

That's it. Start using COSMOS SMS API.