Introduction to Interactive Text API :


Text is a third party API which is can be used by your server app. The Text API allows your server app to send text messages VoicePing’s users. VoicePing users can receive two different types of text.

  1. Text only which is simply a text message.

  2. Interactive with 2 answer options. In Interactive text, users could choose an option and their response will be sent to your server.



Text Only

Interactive Text



API Credentials

You need to send the following to us for us to enable API Usage. Email us sales@smartwalkietalkie.com with the following

  1. Subject: API Access

  2. A registered VoicePing account using Work Email.

  3. A Callback URL for your Server App.


Once we have registered your account for API usage, you will be given the following

  1. Secret token


Using Text API




Parameters

Valid Inputs

API URL

HTTP POST 

https://voiceoverping.net/api/v1/bot/interactive (Production) 

https://staging.voiceoverping.net/api/v1/bot/interactive (Staging)

API Headers

Content-Type

application/json

API Header

x-api-key

{Secret_Token}


A string of alphanumeric characters that we give you when we enable API access.

URL Param

to

{XXXXX}


Numeric individual user ID or group user ID 

URL Param

channel_type

“GROUP” | “PRIVATE”


Select the type of ID you provided in the “To” field

“GROUP” for group “PRIVATE” for individual user



Text Content


To provide the content of the text,  you have to send JSON in HTTP BODY following the format



Text Only

Interactive Text

{

title: “Please go Alice office.”

}

{

title: “Choose your options:”,

options: [{

    title: “Option A”,

    option_id: “opt-a”

},{

    title: “Option B”,

    option_id: “opt-b”

}]

}



If the API call is successful, you will get a message_id back. You need to store this message_id if you plan to use interactive text.


POSTMAN Demo: Send text to a user



Postman 

Send Text to a User

VoicePing App

Receive incoming text



Open POSTMAN and use the follow information.

to: 27409

channel_type: PRIVATE

Body: {

title: “Please go Alice office.”

}


Login on VoicePing App using the following credentials


Username: user2@demotext.com

Password: 1234


user2@demotext.com has user id of 27409




POSTMAN Demo: Send interactive text to a Group



Postman 

Send Interactive Text to a Group

VoicePing App

Receive interactive text


Open POSTMAN and use the follow information.


to: 6630

channel_type: GROUP

BODY: {

title: “can we do private chat”,

options: [{

    title: “YES”,

    option_id: “YES”

},{

    title: “NO”,

    option_id: “NO”

}]

}

Login on VoicePing App using either of the following credentials. As the Text is sent to a group, both users will get the same text and see the above interactive text screen.


Username: user1@demotext.com

Password: 1234


Username: user2@demotext.com

Password: 1234


This screen is valid for 30 seconds. After 30 seconds, no responses will be allowed.




If the user chooses an option, your Callback URL will get their response. 

The Callback response contains the following information

{

    message_id: “0_23_6899_567_t45778686.json”,

    original_message_id: “0_23_678_899_567879897.json”,

    option: {

        title: “Option B”,

        option_id: “opt-b”

    },

    sender_id: 34565,

    created_at: 567879897

}



message_id

Unique Message ID

original_message_id

This is the message ID you got during the first API call to send interactive text.


You need to store the original message ID in the first API call in order to link this response to the original interactive text. 


Note that users could get multiple interactive text and if you do not keep track, you could be linking their response to the wrong question.

option

The option that the user has chosen

sender_id

Which user ID responded

created_at

Time of response