Receive message

    Overview

    Inbound messages are sent from an user’s phone number to your Voxbone DID. By setting up a CallBack URL for Inbound Messages, you will be able to receive the content for each mobile originated (MO) message on your server. The parameters are sent via a POST request to your Callback URL with your Voxbone number appended and Voxbone will be expecting response 200 OK in return, or it will keep retrying for up to 24 hours.

    Authentication and Callback URL

    Our network can send traffic to your server in HTTPS. It is up to you to configure your server accordingly and to configure your callback URL in the SMS link. TLS encryption will be used for delivering the POST request.

    You can choose to implement additional security and have your server respond with a 401 or 403 error with an HTTP Digest challenge instead of sending a 200 OK. In this case, our network will respond with the appropriate hash based on the username & password provisioned in the HTTP link.

    Inbound messages are sent to specific ports so when configuring your callback URL in your SMS link, make sure it points to one of the following ports: 443, 80, 8080, and 8443.


    Request

    Endpoint

    Path Method Description
    /{dest_e164} POST The inbound message is sent to the provisioned callback URL via a POST request with the Voxbone DID that the message was sent to appended

    Request Body Fields

    The inbound message request includes the following parameters:

    Path Method Description
    from String  Sender phone number (with +)
     uuid  String Voxbone Message ID (Up to 36 characters).
     time  String  Time (UTC) when Voxbone first received the message. Format YYYY-MM-DD HH:MM:SS
     msg  String  Inbound message body, UTF8 encoded.
     frag->frag_ref  Integer  ID of group of fragments
     frag->frag_total  Integer  Total number of fragments sms was split into.
     frag->frag_num  Integer  Sequence number of which fragment in group this message is

    Sample Request

    POST http://www.example.com:443/sms/32485111222

    Sample Request Body

    {
    “from” : “+3245546750”,
    “uuid” : “aabF4udH78lpO”,
    “time” : “2015-04-08 09:26:33”,
    “msg” : “Hello dolly!”,
    “frag” : {“frag_ref”:”12″, “frag_total”:”2″, “frag_num”:”1″ }
    }

    Response

    If able to process the SMS the customer must respond with a 200 or 202 response. If unable to process the request at the moment an appropriate error response must be generated, triggering the mechanism for Voxbone to try sending the SMS again later every 15 minutes for 48hrs(depending on whether the error response was final or non-final). In the case of an OK response. A JSON body can be included with the following information:

    Parameter Type Description
    transaction_id String Up to 64 char in length. Should be able to uniquely identify this SMS transaction. Mandatory when Delivery Reports is requested. Optional to have otherwise