What are Trigger SMS Invitations? 

Use Cases 

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 :

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       

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
   

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? 

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.
   

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 ,

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.

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.
   
   

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:

Note: You can add multiple contacts per POST request.

Sample Request     

HTTPS Status Codes

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.