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.
Text only which is simply a text message.
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
Subject: API Access
A registered VoicePing account using Work Email.
A Callback URL for your Server App.
Once we have registered your account for API usage, you will be given the following
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 |