Messaging Documentation

Last updated: September 17th, 2018

Overview

APIGO have a plenty feature to improve your application experience, such as our Apigo Messaging API. Before using APIGO Messaging API, please make sure you have finish the requirement below

  1. Register Account

    Make sure you are already registered in APIGO. If not, go to Register Page

  2. Request Sender ID

    You need sender to send message. You can request Sender at   APIGO Customer Portal. We provide a free Sender ID FREENUM0 for you to try our messaging feature. FREENUM0 can be only used to send message to Telkomsel number

  3. Create Template

    You need template to send message. You can create template using Create New Template at Template Section or you can create through APIGO SMS PORTAL

  4. Add Recipient

    If you want to use Broadcast SMS API, you should create recipient. Broadcast SMS API need recipients group value. So when you want to send broadcast message. Its will send to recipent based group you had inserted. You can create recipient using Add Recipient API at Recipeint Section or you can add through APIGO SMS PORTAL


All Set Up !

After all requirement above is done, you are ready to use APIGO Messaging API. You can get more information and example about our features below.

Request Header

To use APIGO Messaging API, there are 2 module you must fill. They are X-Apigo-Application-Id and X-Apigo-Master-Key. You can get this at your Customer Portal.
Here request headers in CURL format that you must know to user APIGO Messaging API,

curl -X {{API Method}} \
{{API Endpoint}} \
-H 'X-Apigo-Application-Id: {{Your Application ID}}' \
-H 'X-Apigo-Master-Key: {{Your Master Key}}' \

Sender ID

Sender ID is Unique Identity that nedded to send message. As a new user, We give you a free number FREENUM0 that you can used to try our messaging feature. As a note, Sender FREENUM0 only works when your recipients number is Telkomsel.

For Custom Sender, You must request your custom sender at   APIGO Customer Portal. After that, your custom Sender ID need to be aprroved by admin.

Attention!  Aprroved sender id cannot be edited. Please contact our support for further information

Template

Template is the content message. You need to create one before using APIGO Messaging feature. You can create through Create New Template API below or go to APIGO SMS PORTAL. After that. your template need to be approved by admin.

Create New Template

Its possible to create dynamic value using variable with prefix  #(hastag). For example,

Dapatkan diskon belanaja s.d 50% dengan menukarkan kode #param1 ini.
This custom value will be automatically filed by params value you inserted when using Single SMS API or by params value in recipients data when using Broadcast SMS API. For more further information, check Send Message Section

There are 2 data you need to fill, such as

  • Title -> Title of template
  • Content -> Content of template

Endpoint

https://api3.apigo.id/2/messaging/template

This is a sample request :

curl -X POST \
https://api3.apigo.id/2/messaging/template \
-H 'content-type: application/json' \
-H 'X-Apigo-Application-Id: dQR1ZYG' \
-H 'X-Apigo-Master-Key: Vv4dtTCBVbE7BZWpxvZy7ksaos8mHOWa' \
-d '{"title":"Promo Akhir Tahun", "content":"Dapatkan diskon belanaja s.d 50% dengan menukarkan kode #param1 ini."}'

This is a sample response :

{
    "objectId": "oOG26Q5a1J",
    "createdAt": "2018-02-11T22:23:46.105Z"
}

NOTE!   After you create a new template, your template need to be approved by admin first, then you can use its objectId to fiil TemplateId variable at Single SMS API or Broadcast SMS API to send message.

Get All Template

Endpoint

https://api3.apigo.id/2/messaging/template

This is a sample request :

curl -X GET \
https://api3.apigo.id/2/messaging/template \
-H 'content-type: application/json' \
-H 'X-Apigo-Application-Id: dQR1ZYG' \
-H 'X-Apigo-Master-Key: Vv4dtTCBVbE7BZWpxvZy7ksaos8mHOWa'

This is a sample response :

{
    "results": 
    [
        {
            "objectId": "oOG26Q5a1J",
            "approved": true,
            "content": "Dapatkan diskon belanaja s.d 50% dengan menukarkan kode #param1 ini",
            "createdAt": "2018-02-06T15:38:02.968Z",
            "updatedAt": "2018-02-06T15:38:02.968Z"
        },
        {
            "objectId": "je484x7ye5",
            "approved": true,
            "content": "dapatkan cashbak setelah membeli paket #param1",
            "createdAt": "2018-02-11T22:23:46.105Z",
            "updatedAt": "2018-02-11T22:23:46.105Z"
        }
    ]
}
Get One Template

Endpoint

https://api3.apigo.id/2/messaging/template/{{Template Object ID}}

This is a sample request :

curl -X GET \
https://api3.apigo.id/2/messaging/template/oOG26Q5a1J \
-H 'content-type: application/json' \
-H 'X-Apigo-Application-Id: dQR1ZYG' \
-H 'X-Apigo-Master-Key: Vv4dtTCBVbE7BZWpxvZy7ksaos8mHOWa'

This is a sample response :

{
    "objectId": "oOG26Q5a1J",
    "approved": true,
    "content": "Dapatkan diskon belanaja s.d 50% dengan menukarkan kode #param1 ini.",
    "createdAt": "2018-02-11T22:23:46.105Z",
    "updatedAt": "2018-02-11T22:23:46.105Z"
}
Update / Edit Template

Endpoint

https://api3.apigo.id/2/messaging/template/{{Template Object ID}}

This is a sample request :

curl -X PUT \
https://api3.apigo.id/2/messaging/template/oOG26Q5a1J \
-H 'content-type: application/json' \
-H 'X-Apigo-Application-Id: dQR1ZYG' \
-H 'X-Apigo-Master-Key: Vv4dtTCBVbE7BZWpxvZy7ksaos8mHOWa' \
-d '{"title":"Promo Akhir Tahun", "content":"Dapatkan diskon belanaja s.d 50% + 40% dengan menukarkan kode #param1 ini."}'

This is a sample response :

{
    "objectId": "oOG26Q5a1J",
    "updatedAt": "2018-02-11T22:33:21.548Z"
}

NOTE!   You can edit template when your template status is not approved by admin.

Delete Template

Endpoint

https://api3.apigo.id/2/messaging/template/{{Template Object ID}}

This is a sample request :

curl -X DELETE \
https://api3.apigo.id/2/messaging/template/oOG26Q5a1J \
-H 'content-type: application/json' \
-H 'X-Apigo-Application-Id: dQR1ZYG' \
-H 'X-Apigo-Master-Key: Vv4dtTCBVbE7BZWpxvZy7ksaos8mHOWa'

This is a sample response :

{}

Recipient

Recipient is number that plot by user for receiving message. This module will be used at Broadcast SMS API only.

Add Recipient

There are 4 data you need to fill, such as

  • number -> Recipient number
  • params -> this module refer to custom value in Template's Content
  • group -> this module will be used at Broadcast SMS API

Endpoint

https://api3.apigo.id/2/messaging/recipient

This is a sample request :

curl -X POST \
https://api3.apigo.id/2/messaging/recipient \
-H 'content-type: application/json' \
-H 'X-Apigo-Application-Id: dQR1ZYG' \
-H 'X-Apigo-Master-Key: Vv4dtTCBVbE7BZWpxvZy7ksaos8mHOWa' \
-d '{"number":"6285290169655", "params":{"param1":"445"}, "group":"APIGO"}'

This is a sample response :

{
    "objectId": "Ax8oEDqgbr",
    "createdAt": "2018-02-11T20:07:24.444Z"
}
Get All Recipient

Endpoint

https://api3.apigo.id/2/messaging/recipient

This is a sample request :

curl -X GET \
https://api3.apigo.id/2/messaging/recipient \
-H 'content-type: application/json' \
-H 'X-Apigo-Application-Id: dQR1ZYG' \
-H 'X-Apigo-Master-Key: Vv4dtTCBVbE7BZWpxvZy7ksaos8mHOWa'

This is a sample response :

{
    "results": 
    [
        {
            "objectId": "Ax8oEDqgbr",
            "group": "APIGO",
            "number": "6285290169655",
            "params": {
                "param1": "445"
            },
            "createdAt": "2018-02-11T20:16:30.47Z",
            "updatedAt": "2018-02-11T20:16:30.47Z"
        },
        {
            "objectId": "gHyrk8tfr1",
            "group": "APIGO",
            "number": "6285725788886",
            "params": {
                "param1": "777"
            },
            "createdAt": "2018-03-12T20:09:30.74Z",
            "updatedAt": "2018-03-12T20:09:30.74Z"
        }
    ]
}
Get One Recipient

Endpoint

https://api3.apigo.id/2/messaging/recipient/{{Recipient Object ID}}

This is a sample request :

curl -X GET \
https://api3.apigo.id/2/messaging/recipient/Ax8oEDqgbr \
-H 'content-type: application/json' \
-H 'X-Apigo-Application-Id: dQR1ZYG' \
-H 'X-Apigo-Master-Key: Vv4dtTCBVbE7BZWpxvZy7ksaos8mHOWa'

This is a sample response :

{
    "objectId": "Ax8oEDqgbr",
    "group": "APIGO",
    "number": "6285290169655",
    "params": {
        "param1": "445"
    },
    "createdAt": "2018-02-11T20:16:30.47Z",
    "updatedAt": "2018-02-11T20:16:30.47Z"
}
Update / Edit Recipient

Endpoint

https://api3.apigo.id/2/messaging/recipient/{{Recipient Object ID}}

This is a sample request :

curl -X PUT \
https://api3.apigo.id/2/messaging/recipient/Ax8oEDqgbr \
-H 'content-type: application/json' \
-H 'X-Apigo-Application-Id: dQR1ZYG' \
-H 'X-Apigo-Master-Key: Vv4dtTCBVbE7BZWpxvZy7ksaos8mHOWa' \
-d '{"number":"6285290169677"}'

This is a sample response :

{
    "objectId": "Ax8oEDqgbr",
    "updatedAt": "2018-02-11T21:39:21.986Z"
}
Delete Recipient

Endpoint

https://api3.apigo.id/2/messaging/recipient/{{Recipient Object ID}}

This is a sample request :

curl -X DELETE \
https://api3.apigo.id/2/messaging/recipient/Ax8oEDqgbr \
-H 'content-type: application/json' \
-H 'X-Apigo-Application-Id: dQR1ZYG' \
-H 'X-Apigo-Master-Key: Vv4dtTCBVbE7BZWpxvZy7ksaos8mHOWa'

This is a sample response :

{}

Send Message

This module is handling function for sending SMS with 2 types sending method :

  • Single SMS -> This method used to send single message using template with recipient number that you must input it manually
  • Broadcast SMS -> This method used to send broadcast message using template. It's using recipient groups value that you inserted when creating new recipient. Check Recipient Section for further information

Single SMS

Properties field :

  • sender -> String, sender number, refer to data in Sender.
  • recipient -> String, recipient number.
  • templateId -> String, refer data in Template .
  • params -> String, json object string that replace template variable eg. {"kode":"818"}.
  • sandBox -> Boolean, default false, set true if you want to store data only.

Endpoint

https://api3.apigo.id/2/messaging/send/sms/template

This is a sample request :

curl -X POST \
https://api3.apigo.id/2/messaging/send/sms/template \
-H 'content-type: application/json' \
-H 'X-Apigo-Application-Id: dQR1ZYG' \
-H 'X-Apigo-Master-Key: Vv4dtTCBVbE7BZWpxvZy7ksaos8mHOWa' \
-d '{"sender":"FREENUM0", "recipient":"6285290169655", "templateId":"oOG26Q5a1J", "params":{"param1":"818"}, "sandBox":false}'

This is a sample response :

{
    "objectId": "6x9ZGrqkN1",
    "sender": "FREENUM0",
    "recipient": "6285290169655",
    "content": "Dapatkan diskon belanaja s.d 50% dengan menukarkan kode 818 ini.",
    "msgType": "sms",
    "operator": "telkomsel",
    "status": "sending",
    "transactionId": "I001180917150910754695660",
    "sendTime": {
        "__type": "Date",
        "iso": "2018-02-11T23:36:32.671Z"
    },
    "createdAt": "2018-02-11T23:36:32.678Z",
    "updatedAt": "2018-02-11T23:36:32.715Z"
}
Broadcast SMS

Properties field :

  • sender -> String, sender number, refer to data in Sender.
  • group -> String, group name, refer to data in Recipient.
  • templateId -> String, objectId, refer to data in Template.
  • sandBox -> Boolean, default false, set true if you want to store data only.

Endpoint

https://api3.apigo.id/2/messaging/send/sms/template/broadcast

This is a sample request :

curl -X POST \
https://api3.apigo.id/2/messaging/send/sms/template/broadcast \
-H 'content-type: application/json' \
-H 'X-Apigo-Application-Id: dQR1ZYG' \
-H 'X-Apigo-Master-Key: Vv4dtTCBVbE7BZWpxvZy7ksaos8mHOWa' \
-d '{"sender":"FREENUM0", "group":"APIGO", "templateId":"oOG26Q5a1J", "sandBox":false}'

This is a sample response :

{
    "results": 
    [
        {
            "objectId": "6x9ZGrqkN1",
            "sender": "FREENUM0",
            "recipient": "6285290169655",
            "content": "Dapatkan diskon belanaja s.d 50% dengan menukarkan kode 445 ini.",
            "msgType": "sms",
            "operator": "telkomsel",
            "status": "sending",
            "transactionId": "I001180917150910754695660",
            "sendTime": {
                "__type": "Date",
                "iso": "2018-02-11T23:36:32.671Z"
            },
            "createdAt": "2018-02-11T23:36:32.678Z",
            "updatedAt": "2018-02-11T23:36:32.715Z"
        },
        {
            "objectId": "JfbeaTbg56",
            "sender": "FREENUM0",
            "recipient": "6285725788886",
            "content": "Dapatkan diskon belanaja s.d 50% dengan menukarkan kode 777 ini.",
            "msgType": "sms",
            "operator": "indosat",
            "status": "sending",
            "transactionId": "I001180917150910754695660",
            "sendTime": {
                "__type": "Date",
                "iso": "2018-02-11T23:36:32.671Z"
            },
            "createdAt": "2018-02-11T23:36:32.678Z",
            "updatedAt": "2018-02-11T23:36:32.715Z"
        }
    ]
}

Log

History data of sending message is collected in this module.

Get All History

Endpoint

https://api3.apigo.id/2/messaging/log

This is a sample request :

curl -X GET \
https://api3.apigo.id/2/messaging/log \
-H 'cache-control: no-cache' \
-H 'content-type: application/json' \
-H 'X-Apigo-Application-Id: dQR1ZYG' \
-H 'X-Apigo-Master-Key: Vv4dtTCBVbE7BZWpxvZy7ksaos8mHOWa'

This is a sample response :

{
    "results": 
    [
        {
            "objectId": "6x9ZGrqkN1",
            "sender": "FREENUM0",
            "recipient": "6285290169655",
            "content": "Dapatkan diskon belanaja s.d 50% dengan menukarkan kode 445 ini.",
            "msgType": "sms",
            "operator": "telkomsel",
            "status": "sent",
            "transactionId": "8868111100033461",
            "sendTime": {
                "__type": "Date",
                "iso": "2018-02-11T23:36:32.671Z"
            },
            "receiveTime": {
                "__type": "Date",
                "iso": "2018-02-11T23:36:33.711Z"
            },
            "createdAt": "2018-02-11T23:36:32.678Z",
            "updatedAt": "2018-02-11T23:36:32.715Z"
        },
        {
            "objectId": "JfbeaTbg56",
            "sender": "FREENUM0",
            "recipient": "6285725788886",
            "content": "Dapatkan diskon belanaja s.d 50% dengan menukarkan kode 777 ini.",
            "msgType": "sms",
            "operator": "indosat",
            "status": "sent",
            "transactionId": "886811110003362",
            "sendTime": {
                "__type": "Date",
                "iso": "2018-02-11T23:36:32.671Z"
            },
            "receiveTime": {
                "__type": "Date",
                "iso": "2018-02-11T23:36:33.711Z"
            },
            "createdAt": "2018-02-11T23:36:32.678Z",
            "updatedAt": "2018-02-11T23:36:32.715Z"
        }
    ]
}