About bitscio Message Gateway REST API Access

The bitscio Message Gateway RESTful API allows customers to programmatically access bitscio’s SMS/MMS messaging functionality for sending and receiving messages, as well as accessing debug information for messaging activities.

Interaction with our API is limited to HTTPS to ensure session privacy.

Message Gateway Endpoint Information

Here is the base URL by which you will access all resources within this API version:

https://messageapi.orcawave.net/v4

The specific resource that you wish to access must be appended to the end of this base URL. For example, with the messages resource, the complete URL would be:

 https://messageapi.orcawave.net/v4/messages

When binding in, always configure your server with the Orca Wave DNS host name (messageapi.orcawave.net) and not the IP address, IP addresses are subject to change.

Message Gateway Authentication Information

Authentication is required to access the bitscio Messaging API. The authentication requirements consist of Firewall and Credentials described below.

Firewall

All accounts must white list their network server specific IP addresses (/32) or network subnet (/subnet) prior to accessing the bitscio Message Gateway API. IP information is exchanged during the initial account setup and through bitscio support ticketing process for future IP change requests.

Credentials

All API requests to bitscio resources must authenticate using HTTP Basic Access Authentication (encrypted over HTTPS). Your API credentials must be passed in the HTTP header of the request as basic authentication username and password – not as individual parameters within the body of the request – with every API request, as there is no concept of sessions within any API requests/response.

For further information on HTTP Basic Access Authentication, please see: http://en.wikipedia.org/wiki/HTTP_authentication

The Username and Password passed in your API request are your account API key and API secret respectively. Note that some accounts may have multiple credential sets depending on requested configuration. Subsequently, each credential set may have different related permissions to API resources or associated resource assets such as Short Codes, Long Codes or Alphanumeric Codes used for Messaging services.

Encryption and Security

All requests to the bitscio Messaging API over HTTPS are processed using SHA 256 RSA with a 2048 bit algorithm. The use of SSL (Secure Socket Layer) via HTTPS is required for requests to be processed with this encryption level. We require HTTPS over HTTP to ensure a secure and private connection between your application server and our network.

Messages – Send and Receive SMS

API Interface: HTTPS

URI: /v4/messages

Methods: POST

Response Schemas: JSON (default), XML

 

Method POST - Sending an SMS

Request

The following request parameters are available for this resource and method

Required Parameters

  • source [string(15)]

The source code for the message. This must match to one of your codes associated with your connection.

  • destination [string(15)]

The destination number that you want to send the SMS message to. bitscio accepts almost any format while in “friendly format” mode (see the parameter destination Format below). The recommendation for US based numbers is the 11 digit format: “13105551212”.

  • messageText [string(160)]

The SMS message text that you are sending to the end user handset device. This is limited to the general standard of 160 characters unless concatenation is enabled on your account. In some cases your character limit may be less depending on your specific use case and configuration or a carrier limitation

Optional Parameters

  • destinationFormat [integer]

Defaults to 0 for “friendly format” which is the default. If this parameter is passed with a value of 1 then bitscio will expect the destination number in “international format” with the country code (ex. “xXXXxxxXXXX”). This is required for any international messaging.

  • registeredDelivery [integer]

Defaults to 0. If set to 1, this will request a delivery receipt from the carrier which will be delivered to the URL that you specify in your account configuration.

  • destinationPort [String(10)]

Use this parameter when you need your MT (mobile terminate) SMS to be directed to a specific port on the mobile handset device. This parameter should not be passed when sending standard SMS Text messages that are intended for the end user to read.

  • programID [string(25)]

Use this parameter to specify a program ID that is directly related to an approved and certified program or campaign with the carrier/operators. This value is typically only required for Dedicated Short Codes and will be provided as part of your carrier certification.

  • dcs [integer]

Use this to specify the character set that should be used for the message. Defaults to 0 for the SMSC alphabet. Refer to the Data Coding Scheme section for supported DCS values.

Response (Synchronous)

Response Properties

  • version : The requested version of the resource
  • resource : The requested resource name
  • method : The method for the request. This will always be one of the following; GET, POST, UPDATE, DELETE
  • type : The request type; Synchronous or Asynchronous
  • transactionGUID : The globally unique transaction ID for the message
  • destination : Operating company directory number
Method POST - Receiving an SMS

This method is used when bitscio delivers a message from an end user mobile phone or device to your application. The request is initiated by bitscio.

Request

The following request parameters are sent via an HTTP POST to the URL that was defined during your service implementation. Connection/route URL’s can be configured or modified through the bitscio support ticketing process.

Required Parameters

  • transactionGUID [string(36)]

The globally unique transaction ID for the message.

  • connectionGUID [string(36)]

The globally unique identifier for the bitscio network connection in your account which processed the transaction.

  • source [string(15)]

The source address for the message. This is the end user mobile phone which sent you the message.

  • sourceCountry [string(255)]

The registered country name for the number.

  • sourceCountryCode [integer]

The associated country code for the number.

  • sourceCountryAbbreviation [string(2)]

The two-letter country abbreviation (ISO 3166-1 alpha-2)

  • destination [string(15)]

The destination number that the end user sent the message to. This will match with a Short/Long Code configured on your account.

  • messageText [string(160)]

The SMS message text that the end user sent to your Short/Long Code. This is limited to the general standard of 160 characters unless concatenation is enabled on your account. In some cases your character limit may be less depending on your specific use case and configuration or a carrier limitation.

  • concatenatedMessage [string(5)]

true/false

Optional Parameters

  • sourceNational [string(15)]

The source address for the message in national format, excluding the country code. This is the end user mobile phone which sent you the message.

  • udh [string(25)]

Variable length defined inside the UDH itself

  • concatenatedMessageReference [string(5)]

The message reference for a given concatenated message group.

  • concatenatedMessageSegments [integer]

The total number of segments for a given concatenated message.

  • concatenatedMessageSegmentNumber [integer]

The specific message segment number for a given set of segments related to a concatenated message.

  • concatenatedMessageSegmentHash [string(64)] A unique SHA-256 hash that represents the source, destination, message text, total segments, and segment number for the specific segment of a concatenated message. This data can be used to validate a message without requiring an analysis of actual message content which may be restricted by customer privacy laws.

Response (Synchronous or Asynchronous)

bitscio expects to receive an HTTP status code of 200 from your application server which confirms your receipt of the HTTP POST. If we do not receive this HTTP status code, our network will continue to retry the callback to your application until the pre-defined expiration period.

Messages – Send and Receive MMS

API Interface: HTTPS

URI: /v4/messages

Methods: POST

Response Schemas: JSON (default), XML

 

Method POST - Sending an MMS

This method is used to send an MMS message from your application to the bitscio Message Gateway which will be delivered to the end users mobile phone. The request is initiated by your application.

Request

The following request parameters are available for this resource and method

Required Parameters

  • source[string(15)] The source code for the message. This must match to one of your codes associated with your connection.
  • destination[string(15)] The destination number that you want to send the MMS message to. The recommendation for US based numbers is the 11 digit format: “13105551212”.
  • messageText[string(160)] The MMS message text that you are sending to the end user handset device. This is limited to the general standard of 160 characters unless concatenation is enabled on your account. In some cases your character limit may be less depending on your specific use case and configuration or a carrier limitation.
  • mmsURL[string(160)] The URL for the MMS image which is to be sent to the mobile user. This URL must be publicly accessible.

Optional Parameters

  • destinationFormat[integer] Defaults to 0 for “friendly format” which is the default. If this parameter is passed with a value of 1 then bitscio will expect the destination number in “international format” with the country code (ex. “xXXXxxxXXXX”). This is required for any international messaging.
  • registeredDelivery[integer] Defaults to 0. If set to 1, this will request a delivery receipt from the carrier which will be delivered to the URL that you specify in your account configuration.
  • programID[string(25)] Use this parameter to specify a program ID that is directly related to an approved and certified program or campaign with the carrier/operators. This value is typically only required for Dedicated Short Codes and will be provided as part of your carrier certification.
  • mmsSubject[string(40)] This parameter is the “subject” text of the MMS you are sending to the end-user device. This is limited to the general standard of forty characters, but character limit may be less depending upon the use of case and configuration or carrier limitation.

Response (Synchronous or Asynchronous)

Response Properties

The parameters or elements returned in the response to an API request.

  • version: The requested version of the resource
  • resource: The requested resource name
  • method: The method for the request. This will always be one of the following; GET, POST, UPDATE, DELETE
  • type: The request type; Synchronous or Asynchronous
  • transactionGUID: The globally unique transaction ID for the message
  • destination: Operating company directory number
Method POST - Receiving an MMS

This method is used when bitscio delivers a message from an end user mobile phone or device to your application. The request is initiated by bitscio.

Request

The following request parameters are sent via an HTTP POST to the URL that was defined during your service implementation. Connection/route URL’s can be configured or modified through the bitscio support ticketing process.

Required Parameters

  • transactionGUID[string(36)] The globally unique transaction ID for the message.
  • connectionGUID[string(36)] The globally unique identifier for the bitscio network connection in your account which processed the transaction.
  • source[string(15)] The source address for the message. This is the end user mobile phone which sent you the message.
  • sourceCountry[string(255)] The registered country name for the number.
  • sourceCountryCode[integer] The associated country code for the number.
  • sourceCountryAbbreviation[string(2)] The two-letter country abbreviation (ISO 3166-1 alpha-2)
  • destination[string(15)] The destination number that the end user sent the message to. This will match with a Short/Long Code configured on your account.
  • messageText[string(160)] The MMS message text that the end user sent to your Short/Long Code. This is limited to the general standard of 160 characters unless concatenation is enabled on your account. In some cases your character limit may be less depending on your specific use case and configuration or a carrier limitation.
  • mmsURL[string(160)]        The URL for the MMS image which is received from the mobile user. This URL must be publicly accessible.
  • mmsSubject[string(40)] This parameter is the “subject” text of the MMS received from the end-user device. This is limited to the general standard of forty characters, but character limit may be less depending upon the use of case and configuration or carrier limitation.
  • concatenatedMessage[string(5)] true/false
  • attachments Returns information about the multimedia content “attached” to the message.

Optional Parameters

  • sourceNational[string(15] The source address for the message in national format, excluding the country code. This is the end user mobile phone which sent you the message.
  • udh[string(25)] Variable length defined inside the UDH itself
  • concatenatedMessageReference[string(5)] string up to five characters
  • concatenatedMessageSegments[integer]
  • concatenatedMessageSegmentNumber[integer]

Response (Synchronous or Asynchronous)

bitscio will return an HTTP(s) status code in the 200 range upon a successful request along with the following response details. The 200 range could be any of the following values (200, 201, 202, 203, 204, 205, or 206) but in most all cases will be 200. If you do not receive one of these status codes in the response from us, your application should retry the HTTP(s) request at a later date or refer to the specific HTTP status code for more detail.

Messages Status – Get the status of a sent message

API Interface: HTTPS

URI: /v4/messages/{guid}

Methods: GET

Response Schemas: JSON (default), XML

Response Types: Synchronous

Method GET - Check Status

This method is used to query the current status for a message. The request is initiated by your application.

Request

The following request parameters are available for this resource and method

Required Parameters

  • transactionGUID[string(36)] The value of this parameter is the transactionGUID (transaction global unique identifier) for the message that you wish to query a status on. The transactionGUID would have been provided to you in the API response for a previous API request against the Messages API. Important Note: The transactionGUID must be provided in the query string with the request.**

Response (Synchronous)

Response Properties

The parameters or elements returned in the response to an API request.

  • transactionGUID: The globally unique identifier for this transaction or API request
  • transactionGUIDlinked: The globally unique identifier for a related corresponding transaction, if applicable. In the case of a Submit transaction this may represent the corresponding Delivery Receipt or in the case of a Deliver Receipt transaction this will be original Submit transaction.
  • messageType: The type of the message; Submit or Deliver
  • source: The source code/number for the message.
  • destination: The destination code/number for the message.
  • dcs: The data coding scheme that was used in the processing of this message.
  • esmClass: The esmClass that was used in the processing of this message. For example a standard submit message would have an esmClass of 0, while a deliver message of type ‘delivery receipt’ would have an esmClass of 4.
  • status: The current status ID of the message.
  • messageState: The message state for the requested message.
  • registeredDelivery: Denotes whether registered delivery was requested for this message.
  • created: The date the transaction was created in UTC time.
  • processed: The date the transaction was processed in UTC time.
  • completed: The date the transaction was completed in UTC time.
  • lastUpdated: The date the transaction was last Updated in UTC time.

HTTP Status Codes

HTTP Status Codes

**Availability, Access, Security and Authentication Failure
Every API request will result in one of the following common HTTP status codes returned in the response header. The HTTP status codes relate to the API interface request.

Status CodeStatus TypeStatus NameStatus Description
200SuccessCompleted/OKThe synchronous request has been completed
202SuccessCreated/AcceptedThe asynchronous request has been created and will be returned over a callback HTTP POST
301FailureMoved PermanentlyThe requested resource is no longer accessible and has been assigned a new permanent URI. The user agent will not automatically redirect.
400FailureBad RequestThe request cannot be fulfilled due to bad syntax
401FailureUnauthorizedAuthentication is required and has failed or has not yet been provided. Typical Cause: Either the IP server address has not been white listed or the API credentials are not valid.
403FailureForbiddenThe request was a valid request, but the server is refusing to respond to it. Unlike a 401 Unauthorized response, authenticating will make no difference. Typical Cause: The required parameters were not provided in the request.
404FailureNot FoundThe requested resource could not be found but may be available again in the future. Subsequent requests by the client are permissible.
405FailureMethod Not AllowedA request was made of a resource using a request method not supported by that resource; for example, using GET on a form which requires data to be presented via POST.
408FailureRequest TimeoutThe server timed out waiting for the request. The client did not produce a request within the time that the server was prepared to wait. The client MAY repeat the request without modifications at any later time.
500FailureInternal Server ErrorA generic error message, given when an unexpected condition was encountered and no more specific message is suitable.
503FailureService UnavailableThe resource is currently unavailable. Generally, this is a temporary state and subsequent requests by the client are permissible.

Data Coding Scheme

Data Coding Scheme

Data Coding Scheme Values

DCS values signify the Data Coding Scheme you have set to pass your messages to Orca Wave. See the industry-universal list of DCS values below.

IntegerBinaryTranslationNotes
000000000SMSC Default Alphabet
100000001IA5/ASCIIGSM 03.38 (CCITT T.50)/(ANSI X3.4)
200000010Octet Unspecified8-bit binary
300000011Latin 1(ISO-8859-1)
400000100Octet Unspecified8-bit binary
500000101JIS(X 0208-1990)
600000110Cyrllic(ISO-8859-5)
700000111Latin/Hebrew(ISO-8859-8)
800001000UCS2/UTF-16(ISO/IEC-10646)
900001001Pictogram Encoding
1000001010Music Codes(ISO-2022-JP)
1300001101Extended Kanji JIS(X 0212-1990)
1400001110Korean Graphic Character Set(KS C 5601/KS X 1001)

esm_class Parameter

The esm_class parameter is used to indicate special message attributes associated with SMS

Default Setting: 0x00.

If an ESME encodes GSM User Data Header information in the short message user data, it must set the UDHI flag in the esm_class field.

If the SMSC delivers a short message that contains GSM User Data Header information encoded in the short_message or message_payload parameter, it must set the UDHI flag in
the esm_class field.

For GSM networks, the concatenation related optional parameters (sar_msg_ref_num, sar_total_segments, sar_segment_seqnum) or port addressing related optional parameters (source_port, destination_port) cannot be used in conjunction with encoded User Data Header in the short_message (user data) field. This means that the above listed optional
parameters cannot be used if the User Data Header Indicator flag is set.

ESME -> SMSC PDU Encoding

esm_class is encoded as follows in the submit_sm, submit_multi and data_sm (ESME -> SMSC) PDUs:

DictationBits7 6 5 4 3 2 1 0Meaning
Messaging Mode1-0x x x x x x 0 0Default SMSC Mode (e.g. Store and Forward)
Messaging Mode1-0x x x x x x 0 1Datagram mode
Messaging Mode1-0x x x x x x 1 0Forward (i.e. Transaction) mode
Messaging Mode1-0x x x x x x 1 1Store and Forward mode (use to select Store and Forward mode if Default SMSC Mode is non Store and Forward)
Message Type5-2x x 0 0 0 0 x xDefault message Type (i.e. normal message)
Message Type5-2x x 0 0 1 0 x xShort Message contains ESME Delivery Acknowledgement
Message Type5-2x x 0 1 0 0 x xShort Message contains ESME Manual/User Acknowledgement
GSM Network Specific Features7-60 0 x x x x x xNo specific features selected
GSM Network Specific Features7-60 1 x x x x x xUDHI Indicator (only relevant for MT short messages)
GSM Network Specific Features7-61 0 x x x x x xSet Reply Path (only relevant for GSM network)
GSM Network Specific Features7-61 1 x x x x x xSet UDHI and Reply Path (only relevant for GSM network)

SMSC -> ESME PDU Encoding

The esm_class parameter is encoded as follows in a deliver_sm and data_sm (SMSC -> ESME) PDUs:

*Note:*\ All unlisted values for bits 5-2 and 7-6 are reserved.

DictationBits7 6 5 4 3 2 1 0Meaning
Messaging Mode1-0x x x x x x x xnot applicable – ignore bits 0 and 1
Message Type5-2x x 0 0 0 0 x xDefault message Type (i.e. normal message)
Message Type5-2x x 0 0 0 1 x xShort Message contains SMSC Delivery Receipt
Message Type5-2x x 0 0 1 0 x xShort Message contains SME Delivery Acknowledgement
Message Type5-2x x 0 0 1 1 x xreserved
Message Type5-2x x 0 1 0 0 x xShort Message contains SME Manual/User Acknowledgement
Message Type5-2x x 0 1 0 1 x xreserved
Message Type5-2x x 0 1 1 0 x xShort Message contains Conversation Abort (Korean CDMA)
Message Type5-2x x 0 1 1 1 x xreserved
Message Type5-2x x 1 0 0 0 x xShort Message contains Intermediate Delivery Notification
GSM Network Specific Features7-60 0 x x x x x xNo specific features selected
GSM Network Specific Features7-60 1 x x x x x xUDHI Indicator set
GSM Network Specific Features7-61 0 x x x x x xSet Reply Path
GSM Network Specific Features7-61 1 x x x x x xSet UDH and Reply Path