Dinama/Mobisa Message Integration API (send/receive SMS)

Documentation for Dinama/Mobisa SMS

Ver versión en Español

POSTJSon Integration (Recommended)

https://api.dinama.com/services/messages?countryCod=ve&messageFormat=json

Send/Receive SMS notifications using Dinama/Mobisa JSON format

Use Cases:

1) Send a SMS notification:

Client request:

json

{
    "type":"notify",
    "serviceSID":"<Value provided by Dinama/Mobisa>",
    "recipient":"<Phone number international format (without + sign)>",
    "message":"<Text to send>",
    "messageId":"<(optional) Unique message Id, used when delivery status is requested>", 
    "transactionId":"<(optional) Transaction ID>",
    "memo":"<(optional) Category for reports purposes>",
    "sendDate":"<(optional) Date/Time (format yyyymmddHHMMss) when the message must be sent (default: now)>",
    "requestDeliveryStatus":"<(optional) true:To request delivery status, false:delivery status not requested (default false)>",
    "allowConcat": true: To authorize send concatenated messages with or without UCS2(UTF16) encoding when needed 
                   false: Cut message to 160 characters and don't use UCS2(UTF16) encoding (default: false)
                   * View Terms and Conditions
   }

Dinama/Mobisa response:

json

{
     "type":"ack",
     "errorCode":<Processing status (0: request processed, Other: Request failed)>,
     "errorDescription":"<Error description message>"
   }

2) Receive a message sent from the user:

Dinama/Mobisa calls the URL defined by the Client:

json

{
    "type":"request", 
    "serviceSID":"<Value provided by Dinama/Mobisa>",
    "sender":"<Sender Phone number international format (without + sign)>",
    "message":"<Text to send>",
    "transactionId":"<(optional) Transaction ID>",
   }

Client response:

json

{
     "type":"ack",
     "errorCode":<Processing status (0: request processed, Other: Request failed)>,
     "errorDescription":"<Error description message>"
   }

3) Send the response to a message sent by the user:

Client request:

json

{
    "type":"response", 
    "serviceSID":"<Value provided by Dinama/Mobisa>",
    "recipient":"<Phone number international format (without + sign)>",
    "message":"<Text send by the user>",
    "messageId":"<(optional) Unique message Id, used when delivery status is requested>",
    "transactionId":"<(optional) Transaction ID>", 
    "memo":"<(optional) Category for reports purposes>",
    "requestDeliveryStatus":"<(optional) true:To request delivery status, false:delivery status not requested (default false)>",
    "allowConcat": true: To authorize send concatenated messages with or without UCS2(UTF16) encoding when needed 
                   false: Cut message to 160 characters and don't use UCS2(UTF16) encoding (default: false)
                   * View Terms and Conditions
   }

Dinama/Mobisa response:

json

{
     "type":"ack",
     "errorCode":<Processing status (0: request processed, Other: Request failed)>,
     "errorDescription":"<Error description message>"
   }

4) Delivery receipt arrives:

Dinama/Mobisa calls the URL defined by the Client:

json

{
    "type":"receipt", 
    "serviceSID":"<Value provided by Dinama/Mobisa>",
    "recipient":"<Phone number international format (without + sign)>",
    "messageId":"<Unique message Id, associated to this request>", 
    "statusCode":<Delivery Status Cod (10: Message received by the user, 100: Message not sent)>, 
    "statusDescription":"<Delivery status Descripion>"
   }

Client response:

json

{
     "type":"ack",
     "errorCode":<Processing status (0: request processed, Other: Request failed)>,
     "errorDescription":"<Error description message>"
   }

5) Error codes for response messages:

Plain Text

0: No Error, message queued for delivery
   1: Invalid serviceSID
   2: Not authorized 
   3: Transaction Time out 
   4: Missing information
   100: Invalid JSON format
   101: General error

Terms and Condition (If allowConcat is true):

Definitions:

Notification: Content to be sent to each cell phone through text messages.

Message: Each of the segments necessary to send the notification. Under normal conditions, a notification is equivalent to a text message

In the event that the notification exceeds 160 characters, Dinama will segment the messages automatically. For this, it must include special parameters within the message so that it is reassembled as a single message in the subscriber's mobile. By including these special parameters, each segment of the message can contain up to 153 characters. In the same way, if the message contains one or more special characters (such as accented letters or the letter ñ or emoticons), the encoding of the message changes and each message and/or segment can contain up to 67 characters. For all of the above, by accepting these terms and conditions, you agree that:"

Dinama sends as many messages or segments as necessary to deliver the unified message to the subscriber.

The carrier and Dinama charge for each message sent. In this way, if the notification length is longer than 160 characters and/or it has special characters, the defined message must be segmented into multiple parts, the carrier and Dinama will charge for each of the dispatched parts (segments)

HEADERS

content-type

application/json

Content Type of the message format. Always application/json

x-api-key

TaluCLg2Ri9JovkeVtKZS9feS82SaneG66y64eOF

API Key asigned by Dinama/Mobisa in order to access the service

PARAMS

countryCod

Two letter ISO name of the country where the messages are going to be delivered: Options: EC: Ecuador, PR: Puerto Rico, VE: Venezuela

messageFormat

json

Always json

Bodyraw

{
    "type": "notify",
    "serviceSID": "VE-Practipush",
    "recipient": "584100000000",
    "message": "Prueba de Envio"
}

Example Request

curl

curl --location 'https://api.dinama.com/services/messages?countryCod=ve&messageFormat=json' \
--header 'content-type: application/json' \
--header 'x-api-key: TaluCLg2Ri9JovkeVtKZS9feS82SaneG66y64eOF' \
--data '{
    "type": "notify",
    "serviceSID": "VE-Practipush",
    "recipient": "584100000000",
    "message": "Prueba de Envio",
    "messageId": "ID1234",
    "requestDeliveryStatus": false
}'

200 OK

Example Response

json

{
  "type": "ack",
  "errorCode": 0,
  "errorDescription": "OK"
}

Date

Tue, 30 Jul 2019 14:31:07 GMT

Content-Type

application/json

Content-Length

Connection

keep-alive

x-amzn-RequestId

ab2561b3-b2d6-11e9-aba6-79e0eaafa601

x-amz-apigw-id

dpIqzHkYIAMFxMA=

X-Amzn-Trace-Id

Root=1-5d4054ab-f5b32bd535410aceceed1d09

POSTXML1 Integration (Legacy/Obsolete)

https://api.dinama.com/services/messages?countryCod=ve&messageFormat=xml1

Send/Receive SMS notifications using Dinama/Mobisa XML1 format

Use Cases:

1) Send a SMS notification:

Client request:

xml

<?xml version="1.0" encoding="UTF-8"?>
 <push-request>
    <service-id>Value provided by Dinama/Mobisa</service-id>
    <user>Phone number international format (without + sign)</user>
    <text>Text to send</text>
    <category>(optional) Category for reports purposes</category>
    <transaction-id>(optional) Transaction ID</transaction-id>
    <delivery-receipt>(optional) 1 To request delivery status, 0 delivery status not requested (default 0)</delivery-receipt>
    <allow-concat>1: To authorize send concatenated messages with or without UCS2(UTF16) encoding when needed 
                  0: Cut message to 160 characters and don't use UCS2(UTF16) encoding (default: 0)
                  * View Terms and Conditions
    </allow-concat>
    <message-id>(optional) Unique message Id, used when delivery status is requested</message-id>
    <send-date>(optional) Date/Time (format yyyymmddHHMMss) when the message must be sent (default: now)</send-date>
  </push-request>

Dinama/Mobisa response:

xml

<?xml version="1.0" encoding="UTF-8"?>
  <push-response>
    <status>Processing status (0: request processed, Other: Request failed )</status>
    <infor>Status description message</infor>
  </push-response>

2) Receive a message sent from a subscriber:

Dinama/Mobisa request (call to the URL defined by the Client):

xml

<?xml version="1.0" encoding="UTF-8"?>
  <submit-request>
    <service-id>Value provided by Dinama/Mobisa</service-id>
    <user>Phone number international format (without + sign)</user>
    <text>Text sent by the user</text>
    <message-id>(optional) Unique message Id, used when delivery status is requested</message-id>
  </submit-request>

Client Response:

xml

<?xml version="1.0" encoding="UTF-8"?>
  <submit-response>
    <status>Processing status (0: request processed, Other: Request failed )</status>
    <infor>Status description message</infor>
  </submit-response>

3) Send the response to a message sent by the user:

Client request:

xml

<?xml version="1.0" encoding="UTF-8"?>
  <deliver-request>
    <service-id>Value provided by Dinama/Mobisa</service-id>
    <user>Phone number international format (without + sign)</user>
    <text>Text to send</text>
    <transaction-id>(optional) Transaction ID</transaction-id>
    <delivery-receipt>(optional) 1 To request delivery status, 0 delivery status not requested (default 0)</delivery-receipt>
    <allow-concat>1: To authorize send concatenated messages with or without UCS2(UTF16) encoding when needed 
                  0: Cut message to 160 characters and don't use UCS2(UTF16) encoding (default: 0)
                  * View Terms and Conditions
    </allow-concat>
    <message-id>(optional) Unique message Id, used when delivery status is requested</message-id>
  </deliver-request>

Dinama/Mobisa Response:

xml

<?xml version="1.0" encoding="UTF-8"?>
  <deliver-response>
    <status>Processing status (0: request processed, Other: Request failed )</status>
    <infor>Status description message</infor>
  </deliver-response>

4) Delivery receipt arrives:

Dinama/Mobisa request (call to the URL defined by the Client):

xml

<?xml version="1.0" encoding="UTF-8"?>
  <receipt-request>
    <message-id>Unique message Id, associated to this request</message-id>
    <status-code>Delivery Status Cod (10: Message received by the user, 100: Message not sent)</status-coder>
    <status-description>Delivery status Descripion</status-description>
  </receipt-request>

Client response:

xml

<?xml version="1.0" encoding="UTF-8"?>
  <receipt-response>
    <status>Processing status (0: request processed, Other: Request failed )</status>
    <infor>Status description message</infor>
  </receipt-response>

5) Error codes for response messages:

Plain Text

0: No Error, message queued for delivery
   1: Invalid serviceSID
   2: Not authorized 
   3: Transaction Time out 
   4: Missing information
   100: Invalid XML format
   101: General error

Terms and Condition (If allow-concat is 1):

Definitions:

Notification: Content to be sent to each cell phone through text messages.

Message: Each of the segments necessary to send the notification. Under normal conditions, a notification is equivalent to a text message

In the event that the notification exceeds 160 characters, Dinama will segment the messages automatically. For this, it must include special parameters within the message so that it is reassembled as a single message in the subscriber's mobile. By including these special parameters, each segment of the message can contain up to 153 characters. In the same way, if the message contains one or more special characters (such as accented letters or the letter ñ or emoticons), the encoding of the message changes and each message and/or segment can contain up to 67 characters. For all of the above, by accepting these terms and conditions, you agree that:"

Dinama sends as many messages or segments as necessary to deliver the unified message to the subscriber.

The carrier and Dinama charge for each message sent. In this way, if the notification length is longer than 160 characters and/or it has special characters, the defined message must be segmented into multiple parts, the carrier and Dinama will charge for each of the dispatched parts (segments)

HEADERS

Content-Type

text/xml

Content Type of the message format. Always text/xml

x-api-key

TaluCLg2Ri9JovkeVtKZS9feS82SaneG66y64eOF

API Key asigned by Dinama/Mobisa in order to access the service

PARAMS

countryCod

Two letter ISO name of the country where the messages are going to be delivered: Options: EC: Ecuador, PR: Puerto Rico, VE: Venezuela

messageFormat

xml1

Always xml1

Bodyraw

<?xml version="1.0" encoding="ISO-8859-1"?>
<push-request>
    <service-id>VE-Practipush</service-id>
    <user>581111111111</user>
    <text>Prueba Envio</text>
</push-request>

Example Request

curl

curl --location 'https://api.dinama.com/services/messages?countryCod=ve&messageFormat=xml1' \
--header 'Content-Type: application/xml' \
--header 'x-api-key: TaluCLg2Ri9JovkeVtKZS9feS82SaneG66y64eOF' \
--data '<?xml version="1.0" encoding="ISO-8859-1"?>
<push-request>
    <service-id>VE-Practipush</service-id>
    <user>581111111111</user>
    <text>Prueba Envio</text>
</push-request>'

200 OK

Example Response

xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<push-response>
    <status>0</status>
    <infor>OK</infor>
</push-response>

Date

Tue, 30 Jul 2019 14:43:55 GMT

Content-Type

application/json

Content-Length

110

Connection

keep-alive

x-amzn-RequestId

74c8d732-b2d8-11e9-8499-b95a1218962a

x-amz-apigw-id

dpKixG8poAMF1aA=

X-Amzn-Trace-Id

Root=1-5d4057ab-2eda6df498bae5b907aba629

POSTXML2 Integration (Legacy/Obsolete)

https://api.dinama.com/services/messages?countryCod=ve&messageFormat=xml2

Send/Receive SMS notifications using Dinama/Mobisa XML2 format

Use Cases:

1) Send a SMS notification:

Client request:

xml

<?xml version="1.0" encoding="UTF-8"?>
   <practiefectivo-alert>
       <header>
           <bank-id>Value provided by Dinama/Mobisa</bank-id>
           <usr-cod>Phone number international format (without + sign)</usr-cod>
           <transaction-id>(optional) Transaction ID</transaction-id>
           <date-time>Record Date Time. Format: yyyyMMddHHmmss</date-time>
       </header>
       <body>
           <request-alert-status>(optional) 1 To request delivery status, 0 delivery status not requested (default 0)<request-alert-status>
           <message-id>(optional) Unique message Id, used when delivery status is requested</message-id>
           <text>Text to send</text>
           <category>(optional) Category for reports purposes</category>
           <send-date-time>(optional) Date/Time (format yyyymmddHHMMss) when the message must be sent (default: now)</send-date-time>
       </body>
   </practiefectivo-alert>

Dinama/Mobisa response:

xml

<?xml version="1.0" encoding="UTF-8"?>
   <practiefectivo-ack>
       <header>
           <bank-id>Value provided by Dinama/Mobisa</bank-id>
           <usr-cod>Phone number international format (without + sign)</usr-cod>
           <transaction-id>(optional) Transaction ID</transaction-id>
           <date-time>Record Date Time. Format: yyyyMMddHHmmss</date-time>
       </header>
       <body>
           <status>Processing status (0: request processed, Other: Request failed)</status>
           <description>Status description message</description>
       </body>
   </practiefectivo-ack>

2) Receive a message sent from the user:

Dinama/Mobisa request (call to the URL defined by the Client):

xml

<?xml version="1.0" encoding="UTF-8"?> 
   <practiefectivo-request>
       <header>
           <bank-id>Value provided by Dinama/Mobisa</bank-id>
           <usr-cod>Sender Phone number international format (without + sign)</usr-cod>
           <transaction-id>(optional) Transaction ID</transaction-id>
           <date-time>Record Date Time. Format: yyyyMMddHHmmss</date-time>
       </header>
       <body>
           <text>Text send by the user</text>
       </body>
   </practiefectivo-request>

Client response:

xml

<?xml version="1.0" encoding="UTF-8"?>
   <practiefectivo-ack>
       <header>
           <bank-id>Value provided by Dinama/Mobisa</bank-id>
           <usr-cod>Phone number international format (without + sign)</usr-cod>
           <transaction-id>(optional) Transaction ID</transaction-id>
           <date-time>Record Date Time. Format: yyyyMMddHHmmss</date-time>
       </header>
       <body>
           <status>Processing status (0: request processed, Other: Request failed)</status>
           <description>Status description message</description>
       </body>
   </practiefectivo-ack>

3) Send the response to a message sent by the user:

Client request:

xml

<?xml version="1.0" encoding="UTF-8"?>
   <practiefectivo-response>
       <header>
           <bank-id>Value provided by Dinama/Mobisa</bank-id>
           <usr-cod>Phone number international format (without + sign)</usr-cod>
           <transaction-id>(optional) Transaction ID</transaction-id>
           <date-time>Record Date Time. Format: yyyyMMddHHmmss</date-time>
       </header>
       <body>
           <text>Text to send to the user</text>
       </body>
   </practiefectivo-response>

Dinama/Mobisa response:

xml

<?xml version="1.0" encoding="UTF-8"?>
   <practiefectivo-ack>
       <header>
           <bank-id>Value provided by Dinama/Mobisa</bank-id>
           <usr-cod>Phone number international format (without + sign)</usr-cod>
           <transaction-id>(optional) Transaction ID</transaction-id>
           <date-time>Record Date Time. Format: yyyyMMddHHmmss</date-time>
       </header>
       <body>
           <status>Processing status (0: request processed, Other: Request failed)</status>
           <description>Status description message</description>
       </body>
   </practiefectivo-ack>

4) Delivery receipt arrives:

Dinama/Mobisa request (call to the URL defined by the Client):

xml

<?xml version="1.0" encoding="UTF-8"?>
   <practiefectivo-alert-status>
       <header>
           <bank-id>Value provided by Dinama/Mobisa</bank-id>
           <usr-cod>Phone number international format (without + sign)</usr-cod>
           <transaction-id>(optional) Transaction ID</transaction-id>
           <date-time>Record Date Time. Format: yyyyMMddHHmmss</date-time>
       </header>
       <body>
           <status>Delivery Status Cod (10: Message received by the user, 100: Message not sent)</status>
           <description>Delivery status Descripion</description>
           <message-id>Unique message Id, associated to this request</message-id>
           <sent-date-time>Delivery Status Date Time.  Format: yyyyMMddHHmmss</date-time>
       </body>
   </practiefectivo-alert-status>

Client response:

xml

<?xml version="1.0" encoding="UTF-8"?>
   <practiefectivo-ack>
       <header>
           <bank-id>Value provided by Dinama/Mobisa</bank-id>
           <usr-cod>Phone number international format (without + sign)</usr-cod>
           <transaction-id>(optional) Transaction ID</transaction-id>
           <date-time>Record Date Time. Format: yyyyMMddHHmmss</date-time>
       </header>
       <body>
           <status>Processing status (0: request processed, Other: Request failed)</status>
           <description>Status description message</description>
       </body>
   </practiefectivo-ack>

HEADERS

Content-Type

text/xml

Content Type of the message format. Always text/xml

x-api-key

TaluCLg2Ri9JovkeVtKZS9feS82SaneG66y64eOF

API Key asigned by Dinama/Mobisa in order to access the service

PARAMS

countryCod

Two letter ISO name of the country where the messages are going to be delivered: Options: EC: Ecuador, PR: Puerto Rico, VE: Venezuela

messageFormat

xml2

Always xml2

Bodyraw

<?xml version=\"1.0\" encoding=\"ISO-8859-1\"?>
   <practiefectivo-alert>
   	  <header>
   	  	<bank-id>VE-Practipush</bank-id>
   	  	<transaction-id>00001</transaction-id>
   	  	<usr-cod>584100000000</usr-cod>
   	  	<date-time>20190711152331</date-time>
   	  </header>
   	  <body>
   	    	<request-alert-status>0</request-alert-status>
   	    	<message-id>ID1234</message-id>
   	    	<text>Test Message</text>
   	  </body>
   	</practiefectivo-alert>

Example Request

curl

curl --location 'https://api.dinama.com/services/messages?countryCod=ve&messageFormat=xml2' \
--header 'Content-Type: text/xml' \
--header 'x-api-key: TaluCLg2Ri9JovkeVtKZS9feS82SaneG66y64eOF' \
--data '<?xml version=\"1.0\" encoding=\"ISO-8859-1\"?>
   <practiefectivo-alert>
   	  <header>
   	  	<bank-id>VE-Practipush</bank-id>
   	  	<transaction-id>00001</transaction-id>
   	  	<usr-cod>584100000000</usr-cod>
   	  	<date-time>20190711152331</date-time>
   	  </header>
   	  <body>
   	    	<request-alert-status>0</request-alert-status>
   	    	<message-id>ID1234</message-id>
   	    	<text>Test Message</text>
   	  </body>
   	</practiefectivo-alert>'

200 OK

Example Response

xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<practiefectivo-ack>
    <header>
        <bank-id>VE-Practipush</bank-id>
        <transaction-id>00001</transaction-id>
        <usr-cod>584100000000</usr-cod>
        <date-time>20190730104330</date-time>
    </header>
    <body>
        <status>0</status>
        <description>OK</description>
    </body>
</practiefectivo-ack>

Date

Tue, 30 Jul 2019 14:43:30 GMT

Content-Type

application/json

Content-Length

300

Connection

keep-alive

x-amzn-RequestId

660c6895-b2d8-11e9-a844-4d749eed9299

x-amz-apigw-id

dpKe6FFpoAMF9Wg=

X-Amzn-Trace-Id

Root=1-5d405792-356c9ccb8d93eba0b49ecaa3