Trigger SMS Invitations using Zoho Survey API

Trigger SMS Invitations using Zoho Survey API

What are Trigger SMS Invitations? 

Triggers are events that cause a certain action to happen when a pre-defined event occurs.  With Zoho Survey's SMS triggers, users can send survey forms as trigger invitations.
Users can send SMS invitations using the Zoho Survey's REST API on any application by creating an SMS distribution (Contacts based on triggers).

Use Cases 

Hotel Customer Feedback

Suppose you are a restaurateur who wishes to know the customer feedback. Once the customer pays the bill you can send a survey to the customer's phone number via SMS to collect a review.

E-Commerce Survey

You can send an SMS to your customers after product delivery to verify the purchase as well as collect their feedback from your e-commerce system.

Terminologies :

  1. OAuth- An industry-standard protocol that provides secure access to protected resources without giving away the user's password.
  2. Client - An application that sends requests to Zoho Survey to access the triggered invitations on behalf of the end-user.
  3. Client ID- A unique identifier you receive when you register your application with Zoho.
  4. Client Secret- A unique key generated when you register your application with Zoho. This must be kept confidential.
  5. Grant Token- A temporary token used to generate the Access and Refresh tokens. Generating an organization-specific grant token is a one-time process.
  6. Access Token- A token that is sent to the Zoho Survey API to access the triggered invitations of the user. The Access token provides secure and temporary access to Zoho Survey API .Each access token will be valid only for an hour and can be used only for the set of operations that are described in the scope.
  7. Refresh Token- A token that can be used to obtain new access tokens. This token has an unlimited lifetime until it is revoked by the end-user.
  8. API Rate Limit-The API rate limit is the maximum number of API calls that can be simultaneously active at any given point in time.

Pre-Requisites:

  1. Valid Zoho Survey user credentials.
  2. Valid authentication token or OAuth to access Zoho Survey API.
  3. Should have configured the SMS distribution in the Zoho Survey portal.

How To Register your Application :

Enabling the API Trigger invitation begins with registering your client with the Zoho Developer Console.
  1. Register your application with Zoho's Developer console in order to generate your Client ID and Client Secret.
  2. Once the Client ID and Client Secret are generated, generate organization-specific Grant Token   based on your client type using the scope "ZohoSurvey.invitation.CREATE". The Grant token is required only for specific clients like self clients and Server based applications.
  3. Copy the grant token that is generated. Learn More about generating the Client ID and Client Secret for various app types.

Generate Access Token and Refresh Token       

Next, using the Grant token, generate an access token and refresh token with your domain-specific Zoho Accounts URL.
The following are the various domains and their corresponding accounts URLs.
  1. For US: https://accounts.zoho.com
  2. For AU: https://accounts.zoho.com.au
  3. For EU: https://accounts.zoho.eu
  4. For IN: https://accounts.zoho.in
  5. For CN: https://accounts.zoho.com.cn
  6. For JP: https://accounts.zoho.jp
  7. For CA(Canada): https://accounts.zohocloud.ca
  8. For SA(Saudi Arabia): https://accounts.zoho.sa
Notes
Note:
  1. For server based applications, send an authorisation request with the access type parameter value as 'offline'. If the value is offline, you will receive a refresh token along with an access token for the first time you make the request. Once the access token expires, you can use the refresh token to regenerate them.
  2. Each access token is valid for only 1 hour and can only be used for the operations defined in the scope.
  3. To generate a new access token, use the refresh token. A refresh token does not expire. Use the refresh token to re-generate access tokens when they expire.

How to Configure Trigger SMS Invitations? 

Follow the steps below to configure Trigger SMS Invitations using either Zoho SMS Service or third party SMS apps.

Creating SMS Distribution using Zoho SMS Service 

  1. In the Zoho Survey portal, navigate to the Launch tab, then click Create SMS.

  2. Then select the Zoho SMS Service as the Connection. Click on the Import DLT file button and upload your DLT file containing the custom message to be sent as SMS. 

  3. Select the template you have uploaded, and click Use This.

  4. Select the variables you wish to replace the keys in the template. 

  5. Ensure {Surveylink} variable is added as its a mandatory variable.

  6. Once the variables are added click Save.

  7. Verify the template message, and then click Next.  

  8. Then proceed to add the contacts.
Notes
Note:
The uploaded templates have an approval period, only after which they can be sent as SMS Invites. During the approval period, they can also be rejected.
For SMS Service, the template cannot be edited. It can only be replaced or copied from an existing template by clicking the Copy an existing template ,

Creating SMS Distribution using Third-Party App  

  1. In the Zoho Survey portal, navigate to the Launch tab, then click Create SMS.

  2. Choose the Connection type. You can choose different connections by clicking the dropdown button.
  3. Add a custom message using the rich text editor and then proceed to add the contacts by clicking Next.

How to Choose Contacts to send the SMS Invites?

  1. In the Send To section, choose Contacts based on triggers and click Next.

  2. Choose the frequency of triggers as One Time Invite or Recurring Invites.

    1. For One Time Invites:Choose between the following options to set the frequency
      1. Immediately- The SMS invitations will be sent immediately after the Trigger is configured

      2. After a delay- The Trigger can be configured such that the SMS invites will be sent after a particular time interval after trigger initiation.

      3. At a specified date and time- The invites can be scheduled to a specific date and time.

      4. At scheduled time slots- The trigger can be configured as batches at specific time intervals.

    2. For Recurring Invite:If you're choosing Recurring Invites, schedule the frequency of triggers.



  3. Once Create  is clicked , the API Info will be displayed on the success screen, and can be viewed any time to check the API details under Launch > SMS> Triggered Invitations.

Copy the request URL and configure the variables as shown below:
Notes
Note:
The API information is available in the Launch > SMS Distribution > Triggered Invitations > View > API
 
Method  POST
Header     Authorization: Zoho-oauthtoken e4af2b6xxxxxxxxxxxxxbaaba
                       (key)                        (value)
Content-Type: application/json  
 
Method  POST
Header     Authorization: Zoho-oauthtoken e4af2b6xxxxxxxxxxxxxbaaba
                       (key)                        (value)
Content-Type: application/json  
 Request Body   

Request Body:

Parameter
Data type
Description
EmailAddress
string
Specify the SMS address of the contact
phoneNumber*
string
Specify the phone number of the contact.
firstName
string
Specify the first name of the contact.
lastName
string
Specify the last name of the contact.
variableOne
string
You can add this variable field to collect additional data
variableTwo
string
You can add this variable field to collect additional data
variableThree
string
You can add this variable field to collect additional data
variableFour
string
You can add this variable field to collect additional data
variableFive
string
You can add this variable field to collect additional data
variableSix
string
You can add this variable field to collect additional data
* Required fields
 
NotesNote: You can add multiple contacts per POST request.

Sample Request     

Refer to the Sample request below to use the curl command for executing the API:
curl "https://survey.zoho.com/api/v1/external-private/portals/113436589/departments/soCNLR/surveys/123430000050422385/collectors/123430000050422419/distributions/123430000050460139/email/sendinvitation"

-H "Authorization: Zoho-oauthtoken 1000.e4af2b6xxxxxxxxxxxxxbaaba.xa5xxxxxxxxxxxxxxxf"
-d "@contacts.json"
-X POST
In the request, "@contacts.json" contains the sample input data.
Sample Input  
{
"contactsList": [
{
"emailAddress": "bella@example.com",
"phoneNumber": "+1234567890",
"firstName": "bella",
"lastName": "steve",
"variableOne": "variable1",
"variableTwo": "variable2",
"variableThree": "variable3",
"variableFour": "variable4",
"variableFive": "variable5",
"variableSix": "variable6"
},
{
"emailAddress": "john@example.com",
"phoneNumber": "+1234567890",
"firstName": "John",
"lastName": "steve"
}
]
}

HTTPS Status Codes

HTTP Status
Message
Explanation
200 OK
 
If you receive this status, it means the API trigger is successful.
530
ACCESS_RESTRICTED
The distribution is not in trigger state. Verify the API Request URL or create a new distribution with a trigger-based medium.
530
NEED_RECIPIENTS
The contact is empty or if it has an invalid SMS address.
400
INVALID_REQUEST_METHOD
You have specified an invalid HTTP method to access the API URL. Specify a valid request method.
401
OAUTH_SCOPE_MISMATCH
Client does not have the required scope. Create a new client with a valid scope.
530
DISTRIBUTION_DISABLED
The provided triggered invitation is disabled.
530
INVITATION_LIMIT_REACHED
You have exhausted the invitation count limit for the Trigger Expiry.
530
DAILY_EINVITE_LIMIT_REACHED
You have exhausted your daily invite limit.
530
EINVITE_BOUNCE_RATE_EXCEEDED
You have exhausted your account bounce rate limit.
530
EINVITE_COMPLAINT_RATE_EXCEEDED
You have exhausted your account complaint rate limit.

Points To Note

  1. Revoking Refresh Token :You should use your domain-specific Zoho Accounts URL and send a revoke token request in order to revoke the refresh token. Learn more.
  2. Token Validity: There are limits regarding how many tokens can be stored and how many requests can be sent at a time. Learn more.
  3. The API limit on total requests for a distribution per minute is 60.