Robocall User Guide
Contents
1. MP3 MPEG 1 Audio Layer 3 URL Uniform Resource Locator Copyright 2010 Grapevine Interactive Pty Ltd Page 2 of 11 Robocall API user Guide 1 Purpose of this document The purpose of this document is to describe the functionality of the Robocall API and how to use it Note This document does not cover the Robocall front end However you will need to use the front end to view reports When you are provisioned by Grapevine to use Robocall you will receive a user name password and the URL of the application Please contact support vine co za for a copy of the user manual 2 What is Robocall Robocall is a web based application that allows you to send voice messages directly to customers voice mail boxes Robocall also allows you to send XML over HTTP data feeds to automate the uploading of your data In order to do this you will use the Robocall API The Robocall API comprises two requests methods e campaignSetup e sendMessage Robocall is flexible enough so that you can use it to send a single message on demand triggered by your application or in batches of up to 50 at a time up to the daily limit per your commercial agreement with Grapevine To use Robocall you will first create a campaign that include a voice recording and a list of recipients to which you wish to send the voice recording so you should plan your campaign before you create it Please see 5 Planning your Robocall campaign Note Grapevine ca2. lt requestType gt If you are setting up a campaign the default for this tag is always campaignSetup lt name gt You can set up a campaign yourself as in this example or Grapevine can set up a campaign for you You will use the lt name gt tag to identify which campaign and which message should be sent to selected MSISDNs lt scheduleDate gt If this tag is OMITTED the message will be sent immediately else this is the date the message will be sent lt recipient gt The MSISDN s to which you wish to send the message You are only limited by the number of messages you have been provisioned to send in a month as per your commercial agreement with Grapevine Important If you want the campaign to be submitted straight away do not enter a scheduleDate The tag must be omitted not blank sendMessage response lt robocallDatefeedResponse gt lt scheduleDate gt 2011 01 13T09 30 00 lt scheduleDate gt lt recipientsNr gt 2 lt recipientsNr gt lt status gt success lt status gt lt robocallDatefeedResponse gt Copyright 2010 Grapevine Interactive Pty Ltd Page 8 of 11 Response tags explained Robocall API user Guide lt scheduleDate gt This is the date the message was scheduled to be sent If there was no date entered this tag will not be present lt recipientsNr gt lt status gt This is the total number of recipients to which messages were sent You will receive this response when y
3. Document Purpose Version Date Support GRAPEVINE Robocall API User Guide Robocall API User Guide An overview of how to use the Robocall API 1 0 09 July 2010 support vine co za Copyright 2010 Grapevine Interactive Pty Ltd All rights reserved No part of this publication may be reproduced transmitted transcribed stored in a retrieval system or translated into any language in any form or by any means electronic mechanical photocopying recording or otherwise without prior written permission from Grapevine Interactive Pty Ltd All copyright confidential information patents design rights and all other intellectual property rights of whatsoever nature contained herein are and shall remain the sole and exclusive property of Grapevine Interactive Pty Ltd The information furnished herein is believed to be accurate and reliable However no responsibility is assumed by Grapevine Interactive Pty Ltd for its use or for any infringements of patents or other rights of third parties resulting from its use The Grapevine Interactive Pty Ltd name and Grapevine Interactive Pty Ltd logo are trademarks or registered trademarks of Grapevine Interactive Pty Ltd All other trademarks are the property of their respective owners Tel 27 21 702 3333 Email info vine co za Web www vine co za Robocall API user Guide Table of Contents Abbreviations and definitions ssscccssssscccssssscec
4. cssssceccssssceccesssceccsseseccssssessesssssesesseeeoes 2 1 Purpose of this document 2i lt lt ccvccscecseccicssseccscccsscvccescnssscesasascessoesascocsaauceasonstsecaoassesscesars 3 2 What is Robocall zoss ET E EAEN 3 Bi Getting Started eerie areari A EAr E EErEE A EARE Era VAEA 3 A gt Robocall front end a uirri S EA e ENA 4 5 Planning your Robocall campaign essssssesssssssesossssossessoossssoosessoossssossessossessossessoessseoo 4 MP3 Versus DID diraa a aa aaaeei aaa a a aaaea aaa aa aa aiaa eens 4 6 Using the Robocall API step by step ssssssssssessssssssesosessoossssoosesssossssosssssosssssoosessseseseoo 5 The Robocall APL igiccs cine scctveccewsadsccecdevcoeesbosiecdccevacsenseviccacsevacdestessaconsetecdeesayscceeveveeeoeseee 5 7 1 campaignSetup data feed requests and responses cceseesesseceeececeesesnsaeeeeeceesesesesaeeeeeeeseeeees 5 Tekid MP3 reguestandTesponsE susen SE AEEA E 5 7 1 2 DID reg est and respoNS eena raaa EA Esse Pe heen ede 7 7 2 sendMessage data feed request and response ccccccccccscessesssseceeececeesesesseceeeeessesestsaeeeeeeeseeees 8 7 3 Data feed error responsen renane a aoea aA Aaa a RO AAEE ES E Eaa EEE aR EAN AEE ees 9 7 4 EFrOrreSPONSOS AMd SOIUTIONS viez nestaceciedsoesiecte clea elice raea p E a a a a cue Eaa EE ranea aaea 9 8 FAOS ironiei L E EA E TEE E E 11 Abbreviations and definitions API Application Programming Interface DID Direct Inward Dialling
5. de lt campaignData gt lt name gt Christmas lt name gt lt method gt mp3 lt method gt lt mp3Url gt http url tune mp3 lt mp3Url gt lt campaignData gt lt robocallDatafeedRequest gt Note The difference between this and the next request is that there IS an lt mp3Url gt tag Request tags explained lt username gt This will be sent to you by email when you register as a Grapevine Affiliate lt authenticationCode gt This will be sent to you by email when you register as a Grapevine Affiliate lt requestType gt If you are setting up a campaign the default for this tag is always campaignSetup lt name gt You can set up a campaign yourself as in this example or Grapevine can set up a campaign for you You will use the lt name gt tag to identify which campaign and which message should be sent to selected MSISDNs lt method gt The method identifies whether an MP3 file is being used or a Grapevine recording If the former a URL must be entered in the lt mp3Url gt tag lt mp3Url gt If you have entered mp3 in the lt method gt tag you must enter the URL for this file in this tag MP3 response lt robocallDatefeedResponse gt lt status gt success lt status gt lt robocallDatefeedResponse gt Response tags explained lt status gt You will receive this response when your message has been successfully sent If your message is not successfully sent you will receive an error respo
6. est it is MP3 MPEG 1 Audio Layer 3 make a note of the location of this file as you will need to enter the URL when you post your message request DID Direct Inward Dialling before you post your message request you will need to record a message using the Grapevine recording service Note Grapevine s message recording service DID is simply a telephone number you dial that allows you to record the message you want to send in your campaign After you create a campaign and choose DID as your message type you will receive a code from Robocall When you record your message you will be asked to enter this code When the message is sent the code is linked to the correct campaign Copyright 2010 Grapevine Interactive Pty Ltd Page 4 of 11 Robocall API user Guide 6 Using the Robocall API step by step In order to use the Robocall API Step 1 You will need to be provisioned as a Grapevine Affiliate You do this by contacting support vine co za Once provisioned you will receive an email containing your username Affiliate code the URL to which you must post your requests and where appropriate the name of the campaign you must use in your requests if one has been set up for you Alternatively you can set up your own campaign using the campaignSetup data feed request Step 2 If you have chosen to use an MP3 file now you need to create it and upload it to a server where you can point to it using a URL i e it is accessib
7. le over the internet Step 3 Create a campaign or Grapevine will have created one for you by calling the campaignSetup method Step 4 If you are using a Grapevine DID recording you will now need to create the recording using the code you received in the response from posting your campaignSetup request Step 5 Send your message to one or more recipients by posting the sendMessage request Step 6 View your campaign reports online 7 The Robocall API There are two main Robocall data feed requests methods 1 campaignSetup use when you want to create a campaign 2 sendMessage use when you want to send a message for a specified campaign The campaignSetup data feed request method can be further divided into 1 MP3 request and response use when you want to upload an MP3 file 2 DID request and response use when you want to make a DID recording Below are examples of the data feed requests and their responses followed by explanations of their tags Also see 7 4 Error responses and solutions 7 1 campaignSetup data feed requests and responses 7 1 1 MP3 request and response MP3 request Use this XML if you want to upload an MP3 file lt robocallDatafeedRequest gt lt username gt laura lt username gt lt authenticationCode gt SA7U7J7BY lt authenticationCode gt lt requestType gt campaignSetup lt requestType gt Copyright 2010 Grapevine Interactive Pty Ltd Page 5 of 11 Robocall API user Gui
8. message You will receive this message if you have not done the recording Page 10 of 11 Robocall API user Guide 8 FAQs l sent a Robocall message today and the response status was successful but the recipient didn t receive the message Why Robocall messages are sent continuously between 8am and 6pm daily Any messages in the queue outside these hours will not be sent until the next open period Where can I view reports The status of messages can be viewed in the Robocall web based front end Please contact support vine co za for a copy of the user manual How many messages can I send at a time You can see up to 50 messages at a time with a maximum number of messages per month as per your commercial agreement with Grapevine You can view how many messages you have left to send in the Robocall web based front end at the top right of the Home page For assistance contact support vine co za Page 11 of 11
9. n authentication code Make sure you enter it correctly When you are provisioned to use Robocall Grapevine will email you an authentication code Make sure you enter it correctly Contact support vine co za Contact support vine co za Page 9 of 11 Error 106 Authentication failed Robocall not found in Provisioning Central s Applications Error 107 Authentication failed Robocall is disabled Error 201 Invalid data submitted No username Error 202 Invalid data submitted Invalid requestType Error 203 Invalid data submitted No campaignData Error 204 Invalid data submitted No campaignName Error 205 method Invalid data submitted No Error 206 Invalid data submitted No mp3Url Error 207 Invalid data submitted Invalid mp3Url Error 208 Invalid data submitted Invalid method Error 209 Invalid data submitted No recipientsList Error 210 Invalid data submitted Empty recipients list Error 211 Invalid data submitted Wrong date format use yyyy MM ddTHH mmiss Error 301 Campaign setup error campaign name is already used This Error 302 Campaign setup error This campaign has not been setup Error 303 Campaign setup error Sound file was not found when message was sent Copyright 2010 Grapevine Interactive Pty Ltd Robocall API user Guide Contact support vine co za First try again as Robocall may be temporarily disable for maintenance If
10. n create your campaigns for you or you can create them yourself either online or using the Robocall API If Grapevine creates your campaign we will send you the name of the campaign and you will only need to use the sendMessage data feed request 3 Getting started To use the Robocall API you will need to be provisioned as a Grapevine Affiliate You do this by contacting support vine co za Once provisioned you will receive two emails containing the following information depending on whether you are using the API web based application or both e your username e your Affiliate code e the URL to which you must post your requests e the name of the campaign you must use in your requests if one has been set up for you Alternatively you can set up your own campaign using the campaignSetup data feed request e login details and the URL for the online front end Copyright 2010 Grapevine Interactive Pty Ltd Page 3 of 11 4 Robocall API user Guide Robocall front end Robocall has an online front end which you can use to monitor the success of the campaigns you have sent You can also create and send your campaigns from here You will receive details of how to use this service when you are provisioned as a Grapevine Affiliate Please contact support vine co za for a copy of the user manual 5 Planning your Robocall campaign Before using the Robocall API you should Decide whether you want to create your own campaign s
11. nse See 7 3 Data feed error response Copyright 2010 Grapevine Interactive Pty Ltd Page 6 of 11 Robocall API user Guide 7 1 2 DID request and response DID request Use this XML if you want to make a Grapevine recording You must make a note of the DID code in the response which you will have to enter when you create the recording lt robocallDatafeedRequest gt lt username gt laura lt username gt lt authenticationCode gt SA7U7J7BY lt authenticationCode gt lt requestType gt campaignSetup lt requestType gt lt campaignData gt lt name gt Easter lt name gt lt method gt did lt method gt lt campaignData gt lt robocallDatafeedRequest gt Note The difference between this and the previous request is that there is no lt mp3Url gt tag Request tags explained lt username gt This will be sent to you by email when you register as a Grapevine Affiliate lt authenticationCode gt This will be sent to you by email when you register as a Grapevine Affiliate lt requestType gt If you are setting up a campaign the default for this tag is always campaignSetup lt name gt You can set up a campaign yourself as in this example or Grapevine can set up a campaign for you You will use the lt name gt tag to identify which campaign and which message should be sent to selected MSISDNs lt method gt The method identifies whether an MP3 file is being used or a Grapevine recording If the latter you
12. or whether Grapevine should set it up for you Your decision will determine whether you need to use the campaignSetup data feed method or not If you decide to let Grapevine create your campaign you will only need to use the sendMessage data feed method Decide whether you want to make a Grapevine recording or upload an MP3 file Your decision will determine which version of the campaignSetup data feed method to use either the MP3 or DID version Decide when you want to send the campaign Your decision will determine whether you need to include a scheduleDate tag in your sendMessage data feed method or not If you want to send your message immediately you must omit the scheduleDate tag Familiarise yourself with the Robocall front end so you can monitor your campaign after it has been sent You will receive the URL when you are provisioned as a Grapevine Affiliate Contact support vine co za for a copy of the user manual MP3 versus DID There are two ways to add a recorded message to a new campaign you can record a message and save it as a MP3 file to upload when you create your campaign MP3 method or you can use Grapevine s voice message recording service to record a message after your have created your campaign DID method Which method you use is up to you A pre recorded MP3 normally provides better quality audio You will use a different data feed request for each method The requestType tag in the XML identifies which requ
13. our message has been successfully sent If your message is not successfully sent you will receive an error response See 7 3 Data feed error response 7 3 Data feed error response lt robocallDatefeedResponse gt lt status gt error lt status gt lt errorDesc gt Error 101 Authentication failed Username doesn t exist lt errorDesc gt lt robocallDatefeedResponse gt Response tags explained lt status gt You will receive this response when your message has been successfully sent If your message is not successfully sent you will receive an error response See 7 3 Data feed error response lt errorDesc gt This is an explanation of the error which can be used to troubleshoot any problems If you receive an error and need to contact Grapevine support please make a note of this error 7 4 Error Error 101 Authentication failed Username doesn t exist Error 102 Authentication failed The user is not provisioned for Robocall Error 103 Authentication failed Invalid authentication code Error 104 Authentication failed User Account is disabled Error 105 Authentication failed Affiliate Account is disabled Copyright 2010 Grapevine Interactive Pty Ltd Error responses and solutions Solution When you are provisioned to use Robocall Grapevine will email you a username Make sure you enter it correctly When you are provisioned to use Robocall Grapevine will email you a
14. will need the code you receive in the DID response XML you will receive in the reply to your request MP3 response lt robocallDatefeedResponse gt lt didCode gt 9581 lt didCode gt lt status gt success lt status gt lt robocallDatefeedResponse gt Response tags explained lt didCode gt This is the code you will use to create a Grapevine DID recording lt status gt You will receive this response when your message has been successfully sent If your message is not successfully sent you will receive an error response See 7 3 Data feed error response Copyright 2010 Grapevine Interactive Pty Ltd Page 7 of 11 Robocall API user Guide 7 2 sendMessage data feed request and response sendMessage request lt robocallDatafeedRequest gt lt username gt lau lt username gt lt authenticationCode gt SA7U7J7BY lt authenticationCode gt lt requestType gt sendMessage lt requestType gt lt campaignData gt lt name gt New Year lt name gt lt scheduleDate gt 2011 01 13T09 30 00 lt scheduleDate gt lt campaignData gt lt recipientsList gt lt recipient gt 0825540216 lt recipient gt lt recipient gt 0825540217 lt recipient gt lt recipientsList gt lt robocallDatafeedRequest gt Request tags explained lt username gt This will be sent to you by email when you register as a Grapevine Affiliate lt authenticationCode gt This will be sent to you by email when you register as a Grapevine Affiliate
15. you receive the same error contact support vine co za When you are provisioned to use Robocall Grapevine will email you a username Make sure you enter it correctly Make sure the requestType is correct It will be either campaignSetup or sendMessage If you are setting up a campaign the campaignData comprises the campaign name and the type of sound file you are using If you are sending a message the campaignData comprises your recipients MSISDNs Please enter a valid campaignName Please contact support vine co za Ensure you have entered a valid MP3 URL Ensure you have entered a valid MP3 URL Please contact support vine co za Ensure you have at least one recipient MSISDN entered in international format where the leading 0 has been replaced by the South African dialling code 27 e g 078 1234567 gt 27821234567 Ensure you have at least one recipient MSISDN entered in international format where the leading 0 has been replaced by the South African dialling code 27 e g 078 1234567 gt 27821234567 Example 2011 01 13T09 30 00 All campaigns must have a unique name If you receive this message it is because the campaign name is already in use If you are trying to send a message a valid campaign must already be set up If you don t know how to set up a campaign please contact support vine co za If you have chosen to do a Grapevine recording ensure you do this before attempting to send your
Download Pdf Manuals
Related Search