IM Gateway REST API

Samples

Samples

Simplest Request

{
    "destinations": [{
        "number": "356123456"
    }],
    "message": {
        "texts": [{
            "text": "50% discount on our membership fee if you renew your subscription today!"
        }]
    }
}

 

What it does:
  • The message will be delivered to a single mobile number.
  • Since no message plan, sender ID or route were specified, the default values associated to the token declared within the HTTP header will be used.
  • No callback will be sent since a callback URL was not specified
  • Since the request include only text the service will attempt to deliver the message over both SMS and Viber (provided both SMS and Viber channels have been set-up on the API token being used).

Simple Request with text, image, action

{
    "destinations": [{
        "number": "356123456"
    }],
    "message": {
        "texts": [{
            "text": "50% discount on our membership fee if you renew your subscription today!"
        }],
        "images": [{
            "url": "http://example.com/campaigns/fiftypercent.jpg"
        }],
        "actions": [{
            "title": "Renew now!",
            "target_url": "http://example.com/members/renew.php?member_id=356123456"
        }]
    }
}

 

What it does:
  • The message will be delivered to a single mobile number.
  • Since no message plan, sender ID or route were specified, the default values associated to the token declared within the HTTP header will be used.
  • No callback will be sent since a callback URL was not specified
  • Since the request include image and action the service will attempt to deliver the message over Viber, including text, image and button (provided the Viber channel has been set-up on the API token being used).

Request with multiple destinations, Viber preferred, with SMS Fallback

{
   "destinations":[
      {
         "number":"356123456",
         "custom_id":"1",
         "params":{
            "NAME":"Franco",
            "COUNTRY":"Malta"
         }
      },
      {
         "number":"356123457",
         "custom_id":"2",
         "params":{
            "NAME":"Daniel",
            "COUNTRY":"Malta"
         }
      },
      {
         "number":"356123458",
         "custom_id":"3",
         "params":{
            "NAME":"Kevin",
            "COUNTRY":"UK"
         }
      }
   ],
   "job_id":"abc123456",
   "sms_content":{
      	"message":"VDNKa1pYSWdiblZ0WW1WeUlDTXpNekk0SUdseklISmxZV1I1SUdadmNpQndhV05yTFhWd0xpQlNaV2RoY21SekxDQkRiMjF3WVc1NUlFRXU=",
      "encoding":"BINARY",
      "validity_period":86400,
      "udh":"VEVTVFVESA==",
      "pid":4
   },
   "im_content":[
      {
         "channel":"VIBER",
         "content_type":"text",
         "content":"This is a test message to {#NAME} from {#COUNTRY}."
      }
   ],
   "callback_url":"https://example.com/im/callback-sales"
}

 

What it does:
  • This message will be sent to multiple mobile numbers as specified within the destinations block.
  • In this case, overall job ID and custom ID for each destination number have been specified.
  • Message is encoded in BINARY
  • Route, plan and sender ID will be defaulted from token.
  • A call-back will be sent to the specified URL.

 

Request with Viber channel preferred, SMS fallback, and route, plan and sender IDs specified

 
{
   "destinations":[
      {
         "number":"356123456",
         "custom_id":"1",
         "params":{
            "NAME":"Franco",
            "COUNTRY":"Malta"
         }
      },
      {
         "number":"356123457",
         "custom_id":"2",
         "params":{
            "NAME":"Daniel",
            "COUNTRY":"Malta"
         }
      },
      {
         "number":"356123458",
         "custom_id":"3",
         "params":{
            "NAME":"Kevin",
            "COUNTRY":"UK"
         }
      }
   ],
   "job_id":"abc123456",
   "sms_content":{
      "message":"This is a test SMS.",
      "route":"G1",
      "sender_id":"Sales ABC"
   },
   "im_content":[
      {
         "channel":"VIBER",
         "content_type":"text",
         "content":"This is a default test message to {#NAME} from {#COUNTRY}.",
         "sender_id":"CompanyA"
      }
   ],
   "message_plan":"FEATURE_RICH",
   "callback_url":"https://example.com/im/callback-sales"
}

 

What it does:
  • This message will be delivered to multiple mobile numbers, and e ach destination has a custom ID associated to it.
  • JOB ID has been defined.
  • Route, plan and sender ID are specified, both for IM and SMS, thus overriding any default values associated to the token used.
  • Since both an IM content block and an SMS content block have been specified and message_plan is FEATURE_RICH, the service will attempt to deliver this message via IM first, then fallback to SMS if necessary.
  • This request will generate a callback since a callback URL has been specified.

 

Request with text, image, action on Viber channel, with fallback to SMS

 
{
   "destinations":[
      {
         "number":"356123456",
         "custom_id":"1"
      }
   ],
   "im_content":[
      {
         "channel":"VIBER",
         "content":"50% discount on our membership fee if you renew your subscription today!",
         "images": [
             {
                 "url": "http://example.com/campaigns/fiftypercent.jpg"
             }
         ],
         "actions": [
             {
                 "title": "Renew now!", 
                 "target_url": "http://example.com/members/renew.php?member_id=356123456"
             }
         ],
         "expiry_text": "Sorry, this promo has expired!"
      }
   ],
   "sms_content": {
       "message": "50% discount on our membership fee if you renew your subscription today! See http://example.com for more info.", 
       "sender_id": "ABC Sales"
   },
   "message_plan": "FEATURE_RICH", 
   "callback_url": "https://example.com/campaigns/im/status.php"
}

What it does:
  • This message will be delivered to a single mobile number, and the custom_id has been defined.
  • Since message_plan is FEATURE_RICH and both IM content block and an SMS content block have been defined, the service will first attempt to deliver the feature-rich message over Viber, including text, image and button. If for any reason Viber delivery fails, the SMS alternative will be sent.
  • This request will generate a callback since a callback URL has been specified.

 

Request with Viber channel preferred and 2-way messaging enabled


{
 "job_id":"123456",
 "destinations": [
   {
     "number": "356123456"
   }
 ], 
 "im_content": [
   {
     "channel": "VIBER", 
     "sender_id": "Clinic_2way", 
     "content": "You have an appointment scheduled with us tomorrow at 4pm. Can you please confirm your attendance by replying to this message?" 
   }
 ], 
 "callback_url": "https://example.com/campaigns/im/status.php", 
 "reply_url": "https://example.com/campaigns/im/reply.php"
}

What it does:
  • This message will be delivered to a single number.
  • JOB ID has been defined.
  • Since no sms_content block has been defined, this message will be attempted on the Viber channel only.
  • This request will generate a callback since a callback URL has been specified.
  • Since reply_url has also been specified, any replies sent by the message recipient will generate a reply-message callback on the that URL.

Note that this request would require use of a Viber Sender ID with 2-way messaging enabled. 2-way messaging can be enabled on a Sender ID via Fortytwo’s client control panel.

 

Request as promotional message


{  
   "destinations":[  
      {  
         "number":"356123456"
      }
   ],
   "sms_content":{  
      "message":"This is a test message to say hello.",
      "ttl":600
   },
   "im_content":[  
      {  
         "content":"This is a test message to say hello.",
         "ttl":300
      }
   ],

   "promotional": true
}

What it does:
  • This message will be delivered to a single number.
  • The message is set as promotional.

Sample Response

Sample JSON response for request with two destinations.


{
   "api_job_id": "763dd180-6fdd-4991-b433-a4f731ee7db1",
   "client_job_id": "abc123456",
   "result_info": {
         "status_code": 200,
         "description": "Request successful (no errors occured and the message has been submitted)"
   },
   "results": {
         "3561234566": {
            "message_id": "14474342341620024003",
            "custom_id": "2"
         },
         "3561234567": {
            "message_id": "14474342341620014003",
            "custom_id": "1"         
         }
   }
}

Sample Callback

Sample JSON callback for a request delivered via IM.


{
   "api_job_id":"4c2478d3-aebb-4510-8720-1b479d01cfd5",
   "client_job_id":"abc123456",
   "data":[
      {
         "type":"IM_VIBER",
         "message_id":"14182390945378443202",
         "status":"SEEN",
         "timestamp":1422885283,
         "micro_timestamp":1422885283477,
         "to":"35699123457",
         "from":"CompanyA",
         "client_message_id":"2",
         "error_code":0
      }
   ]
}
Get Started