Conference Center API Documentation
API version 1.3 (Last Revised: 10/22/2020)
Contents Purpose of this Document ...... 3 Requests ...... 3 Responses ...... 3 Authentication ...... 4 Accessing Services ...... 5 API Release Support ...... 5 Account Services ...... 6 Get Account Option ...... 6 Specifications ...... 6 Samples...... 7 List International Numbers ...... 8 Specifications ...... 8 Samples...... 8 Meeting Services...... 10 Create Meetings ...... 10 Specifications ...... 10 Samples...... 13 Update Meetings ...... 17 Specifications ...... 17 Samples...... 20 List Meetings ...... 23 Specifications ...... 23 Samples...... 24 Meeting Details ...... 27 Specifications ...... 27 Samples...... 28 Cancel Meeting ...... 31 Specifications ...... 31 Samples...... 31 Invitation Service ...... 33 Create Invitation ...... 33 Specifications ...... 33 Samples...... 34 Registration Services ...... 36 Create Registration ...... 36 Specifications ...... 36 1 Samples...... 38 List Registrations ...... 42 Specifications ...... 42 Samples...... 44 List Poll Questions ...... 47 Specifications ...... 47 Samples...... 48 List Post Event Surveys ...... 49 Specifications ...... 49 Samples...... 50 Chat Service ...... 52 List Chats ...... 52 Specifications ...... 52 Samples...... 53 Recording Services ...... 56 List Recordings ...... 56 Specifications ...... 56 Samples...... 57 Recording Details ...... 59 Specifications ...... 59 Samples...... 60 Recording Registration Service ...... 62 List Recording Registrations ...... 62 Specifications ...... 62 Samples...... 63 Error Specification ...... 66 Code ...... 66 Messages ...... 66 Invalid Value ...... 67 Error Documentation ...... 67 SOAP Errors ...... 67 REST Errors ...... 67 Error Code Table ...... 67 FAQ ...... 68
2 Purpose of this Document This is documentation for the current functionality of the Conference Center SOAP and REST web service API.
Important Notes: • To gain access to the API, you must have an active ReadyTalk account. API access will automatically become available for your account 24 hours after your account has been created. • Downtime window for upgrades and on-going maintenance to the production environment is Fridays between 1p.m. and 4p.m. Mountain time. Please be aware that the service may be down during that time any given week without any notice. Requests The following requests are available with the API: • Get Account Options – Verify what features are enabled for an account. • List International Numbers – View all “On-Demand” International numbers associated with your account. • Create Meetings – Schedule a meeting for a specific date and time. • Cancel Meetings – Cancel a scheduled meeting. • List Meetings – View scheduled meetings associated with your account. • Meeting Details – View specific details about a meeting (i.e. Date & Time, Host, etc.) • Update Meetings – Update an existing scheduled meeting on your account. • Create Invitations – Send email invitations to a list of individuals. • Create Registrations – Register individuals for a specific meeting. • List Registrations – View a list of individuals who have registered for a specific meeting. • List Poll Questions – View a list of poll questions and answers associated with a specific meeting. • List Chats – View a list of chats for a specific meeting. • List Post Event Surveys – View a list of survey questions and responses. • List Recordings – View a list of recordings for a specific account. • Recording Details – View details about a specific recording. • List Recording Registrations – View a list of individuals who registered to view a specific recording. Responses Responses can be retuned in XML or in JSON. By default, all responses will be returned in XML. To receive a response in JSON, add .json to your REST request endpoint URL. Example: https://cc.readytalk.com/api/1.3/svc/rs/meetings.json (This is a listMeetings endpoint) Important Note: SOAP responses can only be returned in XML format. REST responses can be returned in XML or JSON formats.
3
Authentication All requests are authenticated against a valid Account using the HTTP Basic Authentication Scheme. When making requests, the client needs to provide the account credentials in accordance with HTTP 1.1 specification, section 11.1:
HTTP Basic Authentication Specification
Credentials encoded in the HTTP request header must conform to the following format:
Extended Backus-Naur Form credentials = username, “:”, password username = access number, “:”, access code password = passcode
Example (This is a non-working example) username = 8669876543:1234567 password = 1234 credentials = 8669876543:1234567:1234
Steps for using credentials in the header 1. Create the credentials string "8669876543:1234567:1234" (This is a non-working example) 2. Base64 encode that string 3. Append "Basic " in front of the Base64 encoded String (Note: The space is important) 4. Set the ‘Authorization’ request header property to the Base64 encoded String (e.g. ‘Basic sda890eawnfq234908hweroiarn0w’ – This is just an example and should not be used in your request header)
4 Accessing Services You can access a list of services available for the current API version at the following location:
• Production URL: https://cc.readytalk.com/api/1.3/svc
The service home page will contain links for the Account Service, Meeting Service, Registration Service, Chat Service, Recording Service, Recording Registration Service, and WSDL & WADL documents. The WSDL and WADL should be considered the official specification source in the event the information within this document becomes outdated.
To manually schedule meetings, manually update meetings, or manually register individuals for a meeting outside of the API, log into your “Conference Center” using the following URL:
• Production URL: https://cc.readytalk.com
To access training material for the manual options mentioned above, please visit the “Support Center” at https://support.readytalk.com/sp.
Important Note: When sending requests via the API, for any required field that has a default value, the default value is used if no parameter is provided. Otherwise, a value must be provided.
API Release Support Our Web Services API supports versioning. We routinely add new functionality to the API and to prevent these changes from breaking client-side code, we have implemented a versioning scheme. • Current Version: 1.3 • Currently Supported Versions: 1.3 • Versions No Longer Supported: 1.0 & 1.1
5
Account Services This service retrieves account details for the currently authenticated user. All calls must include authentication information in the HTTP request header, as noted previously. • WSDL: https://cc.readytalk.com/ccws-1.3/svc/ws/AccountService?wsdl • WADL: https://cc.readytalk.com/ccws-1.3/svc/rs?_wadl
Get Account Option This service retrieves the current value of the requested account option.
Specifications SOAP Endpoint • Production URL: https://cc.readytalk.com/ccws-1.3/svc/ws/AccountService • WSDL: https://cc.readytalk.com/ccws-1.3/svc/ws/AccountService?wsdl REST Endpoint • Production URL: https://cc.readytalk.com/api/1.3/svc/rs/accounts/option/{optionName} • WADL: https://cc.readytalk.com/ccws-1.3/svc/rs?_wadl • Method: GET Input Parameter (optionName Value) Explanation Constraint ACTIVE string CAN_LOGIN string CAN_USE_WEB_CONFERENCING string CAN_PROMOTE_PARTICPANT_PRESENTER string CAN_GRANT_REMOTE_CONTROL string CAN_CREATE_RECORDING string DELETE_SLIDES_ON_EXIT string CAN_USE_APPSHARE string CAN_USE_CHAT string CAN_USE_SLIDES string CAN_USE_PODCAST string CAN_EDIT_RECORDING string IS_AUDIO_SECURED string MAX_ALLOWED_EMAILS string MAX_ALLOWED_UPLOAD_REGISTRANTS string WEB_ACCESS string
6 Response Element Explanation Constraint name The name of the account option string value A value regarding the state of the account option. A true or string false value will be returned for all options except for the MAX_ALLOWED_EMAILS and MAX_ALLOWED_UPLOAD_REGISTRANTS options. These two options will return a numeric value. Note: All accounts default to 2,000 for both options. Contact Customer Support if this value needs to be increased. Samples SOAP Request
REST Request (GET) https://cc.readytalk.com/api/1.3/svc/rs/accounts/option/ACTIVE
REST Response
7
List International Numbers This service retrieves the current list of international numbers for your account.
Specifications SOAP Endpoint • Production URL: https://cc.readytalk.com/ccws-1.3/svc/ws/AccountService • WSDL: https://cc.readytalk.com/ccws-1.3/svc/ws/AccountService?wsdl REST Endpoint • Production URL: https://cc.readytalk.com/api/1.3/svc/rs/accounts/internationalNumbers • WADL: https://cc.readytalk.com/ccws-1.3/svc/rs?_wadl • Method: GET Input Parameter Explanation Constraint N/A N/A N/A Response Element Explanation Constraint country The country associated with the number string number The telephone number string numberType Toll or Toll-Free string Samples SOAP Request
8
REST Response
9
Meeting Services The meeting services provide access to top level meeting information. Using this service, you can create a scheduled meeting, retrieve a list of scheduled meetings from your account, or get detailed meeting information pertaining to a single meeting. All calls must include authentication information in the HTTP request header, as noted previously. • WSDL: https://cc.readytalk.com/ccws-1.3/svc/ws/MeetingService?wsdl • WADL: https://cc.readytalk.com/ccws-1.3/svc/rs?_wadl
Create Meetings The createMeetings service allows you to create a “Scheduled” meeting.
Specifications SOAP Endpoint • Production URL: https://cc.readytalk.com/ccws-1.3/svc/ws/MeetingService • WSDL: https://cc.readytalk.com/ccws-1.3/svc/ws/MeetingService?wsdl REST Endpoint • Production URL: https://cc.readytalk.com/api/1.3/svc/rs/meetings • WADL: https://cc.readytalk.com/ccws-1.3/svc/rs?_wadl • Method: POST • Content-Type: application/x-www-form-urlencoded
Input (* = Required / * = One or the other value is required) Parameter Explanation Constraint * title Title of meeting string * hostName Name of person or organization hosting the meeting string * fromEmail Email address of the host. Invitations and confirmations will show as sent string from this email address. * startDateIso8601 ISO8601 timestamp for the meeting's scheduled start time. The string meeting start date cannot be in the past. Example: 2015-02- 10T14:00:00.000-07:00 * durationInSeconds Scheduled duration of the meeting in seconds. This will be rounded up to integer the nearest minute. This value must be greater than 0. * timeZone Times will be displayed relative to this time zone in Conference string Center. Use tz (Olson) database entries. Example: America/New_York * registration Valid registration types listed below: string REG_AT_TIME_AUTOMATIC_CONFIRMATION_NO_NOTIFICATION PRE_REG_MANUAL_CONFIRMATION_WITH_NOTIFICATION PRE_REG_AUTOMATIC_CONFIRMATION_WITH_NOTIFICATION PRE_REG_AUTOMATIC_CONFIRMATION_NO_NOTIFICATION
10 * type Valid meeting types listed below: string WEB_AND_AUDIO AUDIO_ONLY WEB_ONLY * audio.onDemand Valid onDemand options listed below: string DISPLAY_TOLLFREE_DISPLAY_TOLL HIDE_TOLLFREE_DISPLAY_TOLL DISPLAY_TOLLFREE_HIDE_TOLL Note: Should only be used for “On-Demand” audio type meetings.
* audio.operatorAssisted.d Enter a “label” of your choice to display before the “value”. string ialInNumber.label Note: This should only be used for “Operator Assisted” audio type meetings. Operator Assisted Meetings must be reserved with our events Character team in order to obtain a unique dial in number for the meeting. In most Limit: cases, this label will be a country name; however, if your meeting Min = 1 includes a Conference ID you should include two labels, each followed Max = 40 by a unique “value”. Your first label would be a country name and your second label should be “Conference ID”.
audio.operatorAssisted.d Enter a number “value”. In most cases, this will be a phone number; string ialInNumber.value however, if your meeting includes a Conference ID you should include two values. Your first value would be a phone number and your second Character value should be the numerical Conference ID. Limit: Note: This should only be used for “Operator Assisted” audio type Min = 1 meetings. The phone number and the Conference ID should have been Max = 40 provided to you by the ReadyTalk Events Team after reserving your Operator Assisted meeting. This number is unique to your meeting and should NOT be your On-Demand phone number.
audio.operatorAssisted.b Enter a Broadcast Audio Code. integer roadcastAudioSetting.co de Note: This should only be used for “Operator Assisted” audio type meetings. This code is only available if you requested this feature when reserving your operator assisted event. If you did not request this feature, leave this parameter out of your createMeetings call. The Broadcast Audio Code should have been provided to you by the ReadyTalk Events Team after reserving your Operator Assisted Broadcast Audio meeting. This number is unique to your meeting.
audio.operatorAssisted.b Enter a phone number (And a Conference ID value if applicable) to string roadcastAudioSetting.dis display to the meeting participants during the live conference. This value playedDialInNumber will always/automatically be prefixed with the words: "To listen via Character phone, dial:" (This does not count against the 40 char limit) Limit: Example: 555-555-1234 & Enter 1122334 Min = 1 Note: This should only be used for “Operator Assisted” audio type Max = 40 meetings. This option is only available if you utilize the audio.operatorAssisted.broadcastAudioSettings.code parameter.
Response Element Explanation Constraint meeting/id Meeting ID. Can be used to get meeting details or registrant information. long meeting/encodedId The base36 encoded meeting ID string title Meeting title string
11
durationInSeconds Duration of the meeting in seconds integer fromEmail Meeting host’s email address string hostName Meeting host’s name string startDateIso8601 ISO8601 timestamp for the meeting's scheduled start time. Meeting start dateTime date cannot be in the past. startDate Meeting start date and start time string timeZone Time zone meeting was scheduled in string status SCHEDULED: Meeting is a scheduled meeting string CANCELLED: Meeting was cancelled CLOSED: Meeting occurred in the past INPROGRESS: Meeting has begun accessCode Access code associated to the meeting. This is used by the participants to join string the meeting via the phone and/or web, when applicable. dialInNumber/label Phone number label (Example: United States or Conference ID) string dialInNumber/value Phone number value (Example: Phone Number or Numeric Conference ID) string meetingType WEB_AND_AUDIO string AUDIO_ONLY WEB_ONLY meetingDetailsPageLink Meeting details page URL string participantUrl/type The type of link provided: string JOIN - Register at time of meeting REGISTRATION - Pre-register before the meeting participantUrl/value Registration or join page URL string campaign/Id List of the IDs of the marketing campaigns set up for the meeting. long Note: Since campaigns cannot be created via the API and can only be manually created via the ReadyTalk Conference Center, only a default campaignId will be returned in this request. Additional campaign information can be obtained via a meetingDetails request after manual creation of the campaign outside of the API. campaign/encodedId List of the Encoded IDs of the marketing campaigns set up for the meeting. string campaign/name List of the names of the marketing campaigns set up for the meeting. string
Informational Tip: If you would like to obtain a unique link that will allow the host of the meeting to launch a specific scheduled meeting, you can create one using the static link below. Simply use the meetingId (Returned in the createMeeting response) and use that to make a meetingDetails request. Take the access code, the conferencing phone number, the passcode, and the encodedId (Returned in the meetingDetails request) and add that to the following static URL. When clicked, this URL will launch the scheduled meeting associated with the encodedId. https://core.readytalk.com/interface/applet.jsp?ac={accessCode}&tf={phone}&pin={passcode}&ev={encodedId}
12 Samples SOAP Request Note: This is for an “On-Demand” Audio Meeting
13
Note: This is for an “On-Demand” Audio Meeting Parameters & Values used with sample POST: Parameters Value title CREATE MEETING REST TEST hostName John Smith fromEmail [email protected] startDateIso8601 2016-02-10T17:00:00.000-07:00 durationInSeconds 3600 timeZone America/Denver registration PRE_REG_AUTOMATIC_CONFIRMATION_NO_NOTIFICATION type WEB_AND_AUDIO audio.onDemand DISPLAY_TOLLFREE_HIDE_TOLL REST Response 1
14
Note: This is for an “Operator Assisted” Audio Meeting with Broadcast Audio. Parameters & Values used with sample POST: Parameters Value title CREATE MEETING REST TEST hostName John Smith fromEmail [email protected] startDateIso8601 2016-02-10T10:00:00.000-06:00 durationInSeconds 5400 timeZone America/Chicago registration PRE_REG_AUTOMATIC_CONFIRMATION_NO_NOTIFICATION type WEB_AND_AUDIO audio.operatorAssisted.dialInNumber.label United States audio.operatorAssisted.dialInNumber.value 555-555-1234 audio.operatorAssisted.dialInNumber.label Conference ID audio.operatorAssisted.dialInNumber.value 1122334 audio.operatorAssisted.broadcastAudioSetting.code 998877 audio.operatorAssisted.broadcastAudioSetting.disp 555-555-1234 & Enter 1122334 layedDialInNumber
15
REST Response 2
16 Update Meetings The updateMeetings service updates a scheduled meeting. Only the owner of a meeting has update access. Meeting fields will only be modified if a parameter is specified.
Specifications SOAP Endpoint • Production URL: https://cc.readytalk.com/ccws-1.3/svc/ws/MeetingService • WSDL: https://cc.readytalk.com/ccws-1.3/svc/ws/MeetingService?wsdl REST Endpoint • Production URL: https://cc.readytalk.com/api/1.3/svc/rs/meetings/{id} • WADL: https://cc.readytalk.com/ccws-1.3/svc/rs?_wadl • Method: PUT • Content-Type: application/x-www-form-urlencoded
Input (* = Required)
Parameter Explanation Constraint * id The ID of the meeting to update. long title The title of the meeting string hostName Name of person or organization hosting the meeting string fromEmail Email address of the host. Invitations and confirmations string will show as sent from this email address. * startDateIso8601 SO8601 timestamp for the meeting's scheduled start time string Example: 2010-11-02T14:00:00.000-07:00 Note: Meeting start date cannot be in the past. durationInSeconds Scheduled duration of the meeting, in seconds. This will integer always be rounded up to the nearest minute. timeZone Time will be displayed relative to this time zone in string Conference Center. sendNotificationEmail Setting sendNotificationEmail = true will send the boolean meetings default "meeting updated" email to all registered participants. type Valid meeting types listed below: string - WEB_AND_AUDIO - AUDIO_ONLY - WEB_ONLY audio.onDemand Valid onDemand options listed below: string - DISPLAY_TOLLFREE_DISPLAY_TOLL - HIDE_TOLLFREE_DISPLAY_TOLL - DISPLAY_TOLLFREE_HIDE_TOLL Note: This should only be used for “On-Demand” audio type meetings.
17 audio.operatorAssisted.d Enter a “label” of your choice to display before the “value”. string ialInNumber.label Note: This should only be used for “Operator Assisted” audio type meetings. Operator Assisted Meetings must be reserved with our events team in order to obtain a unique dial in number for the meeting. In most cases, this label will be a country name; however, if your meeting includes a Conference ID you should include two labels, each followed by a unique “value”. Your first label would be a country name and your second label should be “Conference ID”. audio.operatorAssisted.d Enter a number “value”. In most cases, this will be a phone number; string ialInNumber.value however, if your meeting includes a Conference ID you should include two values. Your first value would be a phone number and your second value should be the numerical Conference ID. Note: This should only be used for “Operator Assisted” audio type meetings. The phone number and the Conference ID should have been provided to you by the ReadyTalk Events Team after reserving your Operator Assisted meeting. This number is unique to your meeting and should NOT be your On-Demand phone number. audio.operatorAssisted.b Enter a Broadcast Audio Code. integer roadcastAudioSetting.co de Note: This should only be used for “Operator Assisted” audio type meetings. This code is only available if you requested this feature when reserving your operator assisted event. If you did not request this feature, leave this parameter out of your createMeetings call. The Broadcast Audio Code should have been provided to you by the ReadyTalk Events Team after reserving your Operator Assisted Broadcast Audio meeting. This number is unique to your meeting. audio.operatorAssisted.b Enter a phone number value to display to the meeting participants during string roadcastAudioSetting.dis the live conference. This value will always be prefixed with the words: "To playedDialInNumber listen via phone, dial:" Note: This should only be used for “Operator Assisted” audio type meetings. This option is only available if you utilize the audio.operatorAssisted.broadcastAudioSettings.code parameter. Response Element Explanation Constraint meeting/id Meeting ID. Can be used to get meeting details or registrant information. long meeting/encodedId The base36 encoded meeting ID string title Meeting title string durationInSeconds Duration of the meeting in seconds integer fromEmail Meeting host’s email address string hostName The name of the meeting host string startDateIso8601 ISO8601 timestamp for the meeting's scheduled start time. Meeting dateTime start date cannot be in the past. startDate Meeting start date and start time string timeZone Time zone meeting was scheduled in string status SCHEDULED: Meeting is a scheduled meeting string CANCELLED: Meeting was cancelled CLOSED: Meeting occurred in the past
18 INPROGRESS: Meeting has begun accessCode Access code associated to the meeting. This is used by the participants string to join the meeting via the phone and/or web, when applicable. dialInNumber/label Number label (Example: United States or Conference ID) string dialInNumber/value Number value (Example: Phone Number or Numeric Conference ID) string meetingType WEB_AND_AUDIO string AUDIO_ONLY WEB_ONLY description The description of the meeting. string Note: This parameter will only be returned if a description exists for the meeting. A description can only be manually entered within the Conference Center. A description cannot be added via the API. meetingDetailsPageLink Meeting details page URL string participantUrl/type The type of link provided: string JOIN - Register at time of meeting REGISTRATION - Pre-register before the meeting participantUrl/value Registration or join page URL string campaign/Id List of the IDs of the marketing campaigns set up for the meeting. long Note: Non-default campaign Ids will only be returned if unique campaigns are setup for a specific meeting within the ReadyTalk Conference Center. Campaigns cannot be created via the API. campaign/encodedId List of the Encoded IDs of the marketing campaigns set up for the string meeting. This campaign encodedId can be appended to the end of this static URL to create the unique campaign URL: https://cc.readytalk.com/r/{encodedId} campaign/name List of the names of the marketing campaigns set up for the meeting. string presenter/name The name(s) of the presenter(s). string Note: This parameter will only be returned if a presenter name has been added to the meeting. This is different from the hostName. A presenter name can only be manually entered within the Conference Center. A presenter name cannot be added via the API. Campaigns cannot be created via the API. presenter/biography The biography(s) of the presenter(s). string Note: This parameter will only be returned if a biography exists for a meeting presenter. A biography can only be manually entered within the Conference Center. A biography cannot be added via the API. Campaigns cannot be created via the API.
19
Samples SOAP Request Note: This is the same sample meeting that was created via the createMeetings SOAP request referenced earlier. The title and the date of that meeting are being updated in this request. Only the parameters that are being updated need to be included in this SOAP request. The response will include all elements, even if they were not updated.
SOAP Response
20 REST Request (PUT) https://cc.readytalk.com/api/1.3/svc/rs/meetings/6913458479853917792
Note: This is the same sample meeting that was created via the first createMeetings REST request referenced earlier. The hostName, hostEmail, and the duration of that meeting are being updated in this request. Only the parameters that are being updated need to be included in this PUT request. The response will include all elements, even if they were not updated.
Parameters & Values being updated with sample PUT: Parameters Value hostName Jane Doe hostEmail [email protected] durationInSeconds 5400 REST Response
21
22 List Meetings The listMeetings service returns a summary view of all meetings that meet the input criteria specified.
Specifications SOAP Endpoint • Production URL: https://cc.readytalk.com/ccws-1.3/svc/ws/MeetingService • WSDL: https://cc.readytalk.com/ccws-1.3/svc/ws/MeetingService?wsdl REST Endpoint • Production URL: https://cc.readytalk.com/api/1.3/svc/rs/meetings • WADL: https://cc.readytalk.com/ccws-1.3/svc/rs?_wadl • Method: GET Input Note: Each of the parameters below are optional. Default values will be used if parameters are not specified. Parameter Explanation Constraint/Default pagingCriteria.firstResultIndex The index of the first desired result as an integer integer Default = 0 pagingCriteria.resultCount Total results to return as an integer integer Default Note: If you need to obtain more than 500 results, you = 25 will need to make additional listMeetings calls and Min = 5 update the firstResultIndex accordingly. Max = 500 Example: A firstResultIndex of 0 and a resutCount of 10 would return your first 10 meetings. To pull over the next 10 meetings, set your firstResultIndex to 10 and leave your resultCount equal to 10. fromDate ISO 8601 formatted date/time string. When provided, string filters to return only meetings scheduled to begin after Default = The earliest this date and time. date available Example: 2015-11-02T14:00:00.000-07:00 Note: It’s ok to neglect the time & only include a date. toDate ISO 8601 formatted date/time string. When provided, string filters to return only meetings scheduled to begin before Default = The furthest this date and time. future date Note: It’s okay to neglect the time & only include a date. fromModifiedDate ISO 8601 formatted date/time string. When provided, string filters to return only meetings that have been modified after this date and time. toModifiedDate ISO 8601 formatted date/time string. When provided, string filters to return only meetings that have been modified before this date and time. includeCancelled Filter to include meetings that were cancelled. boolean Default = false
23
Response Element Explanation Constraint meeting/id Meeting ID. Can be used to get meeting details or registrant long information. meeting/encodedId The base36 encoded meeting ID string title Meeting title string duarationInSeconds Duration of the meeting in seconds integer fromEmail Meeting host’s email address string hostName The name of the meeting host string startDateIso8601 ISO8601 timestamp for the meeting's scheduled start time. dateTime Meeting start date cannot be in the past. startDate Meeting start date and start time string timeZone Time zone meeting was scheduled in string status SCHEDULED: Meeting is a scheduled meeting string CANCELLED: Meeting was cancelled CLOSED: Meeting occurred in the past INPROGRESS: Meeting has begun Samples SOAP Request
24
REST Request (GET) https://cc.readytalk.com/api/1.3/svc/rs/meetings?pagingCriteria.firstResultIndex=0&pagingCriteria.result Count=5&fromDate=2015-12-03&toDate=2015-12-04&includeCancelled=true REST Response
26
Meeting Details The meetingDetails service will return additional information regarding a single scheduled meeting. The meeting ID to be passed into the call should be retrieved from the ID in the listMeetings response.
Specifications SOAP Endpoint • Production URL: https://cc.readytalk.com/ccws-1.3/svc/ws/MeetingService • WSDL: https://cc.readytalk.com/ccws-1.3/svc/ws/MeetingService?wsdl REST Endpoint • Production URL: https://cc.readytalk.com/api/1.3/svc/rs/meetings/{id} • WADL: https://cc.readytalk.com/ccws-1.3/svc/rs?_wadl • Method: GET
Input (* = Required) Parameter Explanation Constraint * id The ID of the meeting for which you want details long Response Element Explanation Constraint meeting/id Meeting ID. Can be used to get meeting details or registrant information. long meeting/encodedId The base36 encoded meeting ID string title Meeting title string durationInSeconds Duration of the meeting in seconds integer fromEmail Meeting host’s email address string hostName The name of the meeting host string startDateIso8601 ISO8601 timestamp for the meeting's scheduled start time. Meeting start dateTime date cannot be in the past. startDate Meeting start date and start time string timeZone Time zone meeting was scheduled in string status SCHEDULED: Meeting is a scheduled meeting string CANCELLED: Meeting was cancelled CLOSED: Meeting occurred in the past INPROGRESS: Meeting has begun accessCode Access code associated to the meeting. This is used by the participants to string join the meeting via the phone and/or web, when applicable. dialInNumber/label Number label (e.g. United States or Conference ID) string dialInNumber/value Number value (e.g. Phone Number or Numeric Conference ID) string
27 meetingType WEB_AND_AUDIO string AUDIO_ONLY WEB_ONLY description The description of the meeting. string Note: This parameter will only be returned if a description exists for the meeting. A description can only be manually entered within the Conference Center. A description cannot be added via the API. meetingDetailsPageLink Meeting details page URL string participantUrl/type The type of link provided: string JOIN - Register at time of meeting REGISTRATION - Pre-register before the meeting participantUrl/value Registration or join page URL string campaign/Id List of the IDs of the marketing campaigns set up for the meeting. Note: long Non-default campaign Ids will only be returned if unique campaigns are setup for a specific meeting within the ReadyTalk Conference Center. Campaigns cannot be created via the API. campaign/encodedId List of the Encoded IDs of the marketing campaigns set up for the string meeting. This campaign encodedId can be appended to the end of this static URL to create the unique campaign URL: https://cc.readytalk.com/r/{encodedId} campaign/name List of the names of the marketing campaigns set up for the meeting. string presenter/name The name(s) of the presenter(s). string Note: This parameter will only be returned if a presenter name has been added to the meeting. This is different from the hostName. A presenter name can only be manually entered within the Conference Center. A presenter name cannot be added via the API. Campaigns cannot be created via the API. presenter/biography The biography(s) of the presenter(s). string Note: This parameter will only be returned if a biography exists for a meeting presenter. A biography can only be manually entered within the Conference Center. A biography cannot be added via the API. Campaigns cannot be created via the API. Samples SOAP Request
28
SOAP Response
REST Request (GET) https://cc.readytalk.com/api/1.3/svc/rs/meetings/4889561245321548759 REST Response
29
30
Cancel Meeting Use this endpoint to cancel a specific meeting.
Specifications SOAP Endpoint • Production URL: https://cc.readytalk.com/ccws-1.3/svc/ws/MeetingService • WSDL: https://cc.readytalk.com/ccws-1.3/svc/ws/MeetingService?wsdl REST Endpoint • Production URL: https://cc.readytalk.com/api/1.3/svc/rs/meetings/{id} • WADL: https://cc.readytalk.com/ccws-1.3/svc/rs?_wadl • Method: DELETE
Input (* = Required) Parameter Explanation Constraint/Default * id The ID of the meeting to cancel. long sendCancellationEmail Parameter to determine whether or not to send cancellation Boolean emails to invitees or registered participants Default = false Response Element Explanation Constraint id The ID of the meeting that was requested to be modified. long cancellationStatus Whether or not the meeting is cancelled boolean cancellationEmailSent Whether or not cancellation emails were sent to invitees or boolean registered participants. Samples SOAP Request
31
SOAP Response
REST Request (DELETE) https://cc.readytalk.com/api/1.3/svc/rs/meetings/4162256738970523012?sendCancellationEmail=true
REST Response
32
Invitation Service This service handles the sending of invitation emails. All calls must include authentication information in the HTTP request header, as noted previously. • WSDL: https://cc.readytalk.com/api/1.3/svc/ws/RegistrationService?wsdl • WADL: https://cc.readytalk.com/ccws-1.3/svc/rs?_wadl
Create Invitation This request handles the sending of invitation emails.
Specifications SOAP Endpoint • Production URL: https://cc.readytalk.com/api/1.3/svc/ws/RegistrationService • WSDL: https://cc.readytalk.com/ccws-1.3/svc/ws/RegistrationService?wsdl REST Endpoint • Production URL: https://cc.readytalk.com/api/1.3/svc/rs/invites • WADL: https://cc.readytalk.com/ccws-1.3/svc/rs?_wadl • Method: POST • Content-Type: application/x-www-form-urlencoded
Input (* = Required) Parameter Explanation Constraint * meetingId ID of the meeting for which invitations should be generated. long * email One or more email addresses for recipient of the invitation. string Note: There is a 2,000 invitation email limit per meeting. Contact Customer Support if this value needs to be increased. campaignId Campaign ID of the meeting for which invitations should be long generated. If not included, the default campaign ID is used. Response Element Explanation Constraint id The unique ID for the email invitation long encodedId The base36 encoded invitation ID string email The email address the invitation was sent to string meetingId The meeting ID the invitation was sent for long campaignId The campaign ID associated with the meeting this invitation was sent long for optOutEmail A string containing the email address to which an invitation was not string sent to, as they had previously opted-out of any correspondence voluntarily. 33
Samples SOAP Request
REST Request (POST) https://cc.readytalk.com/api/1.3/svc/rs/invites
Parameters & Values used with sample POST: Parameters Value meetingId 2236297219522087625 email [email protected] email [email protected] email [email protected] email [email protected] email [email protected]
34
REST Response
35
Registration Services This service handles meeting registrations and handles the returning of post-meeting data such as attendance, polling information, and post event survey information. All calls must include authentication information in the HTTP request header, as noted previously. • WSDL: https://cc.readytalk.com/api/1.3/svc/ws/RegistrationService?wsdl • WADL: https://cc.readytalk.com/ccws-1.3/svc/rs?_wadl Create Registration The createRegistration call will register a participant for a meeting using first name, last name, and email address at a minimum. Eighteen additional standard questions may also be used. It is optional whether or not a confirmation email is sent from ReadyTalk for each registrant. Specifications SOAP Endpoint • Production URL: https://cc.readytalk.com/ccws-1.3/svc/ws/RegistrationService • WSDL: https://cc.readytalk.com/ccws-1.3/svc/ws/RegistrationService?wsdl REST Endpoint • Production URL: https://cc.readytalk.com/api/1.3/svc/rs/registrations • WADL: https://cc.readytalk.com/ccws-1.3/svc/rs?_wadl • Method: POST • Content-Type: application/x-www-form-urlencoded Input Note: If you include the optional field parameters within your createRegistration request and you would like that information to be available to view/export within your ReadyTalk Conference Center, you will need to manually adjust the registration form for your meeting(s). Parameter Required? Explanation Constraint meetingId Yes The id of the meeting to create the registration for. long firstName Yes The first name of the registrant. string lastName Yes The last name or family name of the registrant. string email Yes The email address of the registrant. string campaignId No Campaign ID of the meeting for which registration should long be tied to. If not included, the default campaign ID is used. phone No The phone number of the registrant. string mobilePhone No The mobile phone number of the registrant. string fax No The fax machine phone number of the registrant. string jobTitle No The job title of the registrant. string company No The company of the registrant. string department No The department of the registrant. string industry No The industry of the registrant. string
36 addressStreet1 No The first line of the address field of the registrant. string addressStreet2 No The second line of the address field of the registrant. string addressStreet3 No The third line of the address field of the registrant. string city No The city the registrant resides in. string state No The state the registrant resides in. string zip No The zip code the registrant resides in. string country No The country the registrant resides in. string website No The website URL of the registrant. string annualRevenue No The annual revenue of the registrant. string employeeCount No The employee count of the registrant. string purchaseTimeFrame No The purchasing time frame of the registrant. string preventDuplicates No A boolean that specifies whether to prevent duplicate boolean registration entries from being created. A registration is Default = considered a duplicate when another registration has false already been created for the same meeting with the specified email address. Note: If a second registration is submitted and the preventDuplicates value is “true”, the registrant’s original registration information will be included in the response. sendConfirmationEmail No A boolean that specifies whether to send a confirmation boolean email to the registrant, confirming they are registered for Default = the meeting. If the request is successful, the email address false provided above will receive a confirmation email. Response
Element Explanation Constraint id The unique id of the registrant long encodedId The base36 encoded registration ID. string campaignId The ID of the marketing campaign used by an individual to register for a meeting. long surveyId Unique version of the survey answered long status The status of the registrant. string CONFIRMED: Occurs after an individual registers for a meeting and has been automatically confirmed by the system or manually confirmed by the host. PENDING: Occurs after an individual registers for a meeting setup with the “Manually Confirm” feature and the host has yet to confirm the individual. DECLINED: Occurs if an individual registered for the meeting but was declined by the host of the meeting. attended Checks if the registrant attended the meeting. boolean firstName Answer to the first name question on the registration form. string lastName Answer to the last name question on the registration form. string email Answer to the email question on the registration form. string questionId The ID value of the registration question. long questionText The question as it appears on the registration form. string value The response value to the registration question on the form. string joinMeetingUrl The unique join meeting URL for the registrant. string
37
Informational Tip 1: Add to Calendar URL’s are not included in API responses. • If your sendConfirmationEmail value is “true”, then Add to Calendar URL’s will automatically be included on the emails sent out of the ReadyTalk system. • If the sendConfirmationEmail value is false, you are sending out your own personal emails, and you would like to include Add to Calendar links in your personal emails, you can take each registrant’s unique encodedId that is returned in the createRegistration response and append that to the following static URL’s to create unique Add to Calendar URL’s for each registrant. Outlook Add to Calendar: https://cc.readytalk.com/cc/schedule/iCalCreation.do?regId={encodedId} Google Add to Calendar: https://cc.readytalk.com/gcal/r/{encodedId} Informational Tip 2: When registrants click on their Join Meeting URL, they are prompted to verify their email address before they are brought into the live conference. This is done as an additional security measure to ensure that Join Meeting URLs are not shared. This security step can be bypassed if desired. To do so, append &email= to the end of each registrants unique Join Meeting URL and then add their email address (This option is only possible when you are sending out personal emails and the sendConfirmationEmail value is set to “false”. Example: https://cc.readytalk.com/partlogin/[email protected] Note: By bypassing this security measure, anyone who has access to a unique Join Meeting URL can access the meeting. Samples SOAP Request
38
39
REST Request (POST) https://cc.readytalk.com/api/1.3/svc/rs/registrations
Parameters & Values used with sample POST: Parameters Value meetingId 451212451845158745 firstName John lastName Smith email [email protected] Company ReadyTalk preventDuplicates true sendConfirmationEmail true REST Response
40
41
List Registrations The listRegistrations call will return a list of people who have registered and/or attended a scheduled meeting. This call can retrieve all registration records that have been updated since a specific date and time, providing for incremental update capabilities. If a participant exits and enters a meeting multiple times, there will be multiple attendance entry and exit records associated with them.
Specifications SOAP Endpoint • Production URL: https://cc.readytalk.com/api/3.1/svc/ws/RegistrationService/listRegistrations • WSDL: https://cc.readytalk.com/ccws-1.3/svc/ws/RegistrationService?wsdl REST Endpoint • Production URL: https://cc.readytalk.com/api/1.3/svc/rs/registrations • WADL: https://cc.readytalk.com/ccws-1.3/svc/rs?_wadl • Method: GET
Input (* = Required) Parameter Explanation Constraint * meetingID The id of the meeting you want a registration list for long fromDate ISO 8601 formatted date/time string. When provided, string filters to return only individuals who registered after Default = The this date and time. earliest date Example: 2015-11-02T14:00:00.000-07:00 available Note: It’s ok to neglect the time & only include a date. pagingCriteria.firstResultIndex The index of the first desired result as an integer integer Default = 0 pagingCriteria.resultCount Total results to return as an integer integer Default = Note: If you need to obtain more than 500 results, 25 you will need to make additional listRegistration calls Min = 5 and update the firstResultIndex accordingly. Max = 500 Example: A firstResultIndex of 0 and a resutCount of 10 would return your first 10 registrants. To pull over the next 10 registrants, set your firstResultIndex to 10 and leave your resultCount equal to 10.
42
Response Element Explanation Constraint registration/id Unique identifier for the registered attendee. (This is the long same id value that is returned in the listPostEventSurvey response. This id is one way for you to decipher who responded to each survey question). registration/encodedId The Base36 encoded version of the id. string campaignId The id of the campaign the user registered under. long surveyId The unique version of the survey answered. long status The status of the registrant. string CONFIRMED: Occurs after an individual registers for a meeting and has been automatically confirmed by the system or manually confirmed by the host. PENDING: Occurs after an individual registers for a meeting setup with the “Manually Confirm” feature and the host has yet to confirm the individual. DECLINED: Occurs if an individual registered for the meeting but was declined by the host of the meeting. attended Checks if the registrant attended the meeting. boolean firstName Answer to the first name question on the registration string form. lastName Answer to the last name question on the registration string form. email Answer to the email question on the registration form. string registrationAnswer/question/questionId The id value of the question. long registrationAnswer/question/questionText The question as it appears on the registration form. string registrationAnswer/response/value The registrant's response to the question. string attendance/id The unique attendance record id, if meeting conducted integer (This is the same id value that is returned in the listPostEventSurvey response. This id is one way for you to decipher who responded to each survey question). conferenceId The id of the conference the individual attended. If a integer meeting is stopped/started multiple times then a unique conferenceId is assigned to each instance of the meeting. entryTime The timestamp for when the individual entered the string meeting in ISO8601 format. exitTime The timestamp for when the individual disconnected from string the meeting in ISO8601 format. durationInMinutes The length of time an individual was in the conference. integer Note: This is rounded up to the next minute. pollAnswer/question/questionId The id of the poll question. long pollAnswer/ question/questionText The text of the poll question to be asked. string
43
pollAnswer/response/value The value of the response given to the poll question string asked. pollAnswer/response/rank The integer rank of the poll response chosen. This integer only applies to ranking type questions. joinMeetingUrl The unique join meeting URL for the registrant. string Samples SOAP Request
SOAP Response
REST Request (GET) https://cc.readytalk.com/api/1.3/svc/rs/registrations?meetingID=217276528027146225&fromDate=2016-1-18&pa gingCriteria.firstResultIndex=0&pagingCriteria.resultCount=5 REST Response
45
46
List Poll Questions This service can be used to list all of the poll questions that have been created under a specific access code. Note: This service will only list the current poll questions for a given access code. It will not list meeting participants or their responses to the poll questions. If you would like to obtain a list of meeting participants and their poll responses, use the List Registration service.
Specifications SOAP Endpoint • Production URL: https://cc.readytalk.com/ccws-1.3/svc/ws/RegistrationService • WSDL: https://cc.readytalk.com/ccws-1.3/svc/ws/RegistrationService?wsdl REST Endpoint • Production URL: https://cc.readytalk.com/api/1.3/svc/rs/registrations/pollQuestions • WADL: https://cc.readytalk.com/ccws-1.3/svc/rs?_wadl • Method: GET Input Parameter Explanation Constraint includeDeleted Filter to include deleted poll questions. boolean Default = false pagingCriteria.firstResultIndex The index of the first desired result as an integer integer Default = 0 pagingCriteria.resultCount Total results to return as an integer integer Default = Note: If you need to obtain more than 500 results, you will 25 need to make additional listPollQuestions calls and update the Min = 5 firstResultIndex accordingly. Max = 500 Example: A firstResultIndex of 0 and a resutCount of 10 would return your first 10 polls. To pull over the next 10 polls, set your firstResultIndex to 10 and leave your resultCount equal to 10. Response Element Explanation Constraint totalResultCount The total number of results found by the query made. integer pollQuestion/questionId The id value of the poll question. long pollQuestion/questionText The text of the poll question to be asked. string
47
Samples SOAP Request
REST Request (GET) https://cc.readytalk.com/api/1.3/svc/rs/registrations/pollQuestions?pagingCriteria.firstResultIndex=0&pa gingCriteria.resultCount=5 REST Response
48
List Post Event Surveys This service returns the post event survey questions and responses for a specified meeting. Notes: • This service does not currently support the creation of surveys using the API. Surveys must be manually created within your ReadyTalk account after the meeting is scheduled. Visit the ReadyTalk Support Center for more information about creating surveys. • Registrants names are not returned with this service. Instead, the meeting participant’s unique registrationId is returned. To identify the name of the registrant, utilize the listRegistration service and match the registrationId from that service with the registrationId from the listPostEventSurvey service.
Specifications SOAP Endpoint • Production URL: https://cc.readytalk.com/ccws-1.3/svc/ws/RegistrationService • WSDL: https://cc.readytalk.com/ccws-1.3/svc/ws/RegistrationService?wsdl REST Endpoint • Production URL: https://cc.readytalk.com/api/1.3/svc/rs/registrations/surveys • WADL: https://cc.readytalk.com/ccws-1.3/svc/rs?_wadl • Method: GET
Input (* = Required) Parameter Explanation Constraint * meetingId The ID of the meeting for which survey info is desired. long pagingCriteria.firstResultIndex The index of the first desired result as an integer integer Default = 0 pagingCriteria.resultCount Total results to return as an integer integer Default Note: If you need to obtain more than 500 results, you will = 25 need to make additional listPostEventSurveys calls and Min = 5 update the firstResultIndex accordingly. Max = 500 Example: A firstResultIndex of 0 and a resutCount of 10 would return your first 10 survey results. To pull over the next 10 survey results, set your firstResultIndex to 10 and leave your resultCount equal to 10.
49
Response Element Explanation Constraint totalResultCount The total number of results found by the query made. integer customLink If you added a re-direct link to your meeting instead of directing users to string the ReadyTalk survey at the conclusion of your meeting, then the customLink element would be the only element provided in the response. A customLink element will not be returned if a survey was used. registrationId The unique id value of the registrant. long Note: To identify the name of the registrant, utilize the listRegistration service and match the registrationId from that service with the registrationId from the listPostEventSurvey service. surveyAttendance/id The unique attendance id value of the individual who attended the long conference. conferenceId The id value of the conference the individual attended. If a meeting is long stopped/started multiple times then a unique conferenceId is assigned to each instance of the meeting. entryTime Timestamp for when the individual entered the meeting in ISO8601 format dateTime exitTime Timestamp for when the individual disconnected from the meeting in dateTime ISO8601 format. durationInMinutes The length of time the individual was in the conference, rounded up to the integer next minute. questionId The id value of the survey question. long questionText The survey question. string value The response given to the survey question. string Samples SOAP Request
51
Chat Service This service returns all chat data for a specified meeting. All calls must include authentication information in the HTTP request header, as noted previously. • WSDL: https://cc.readytalk.com/ccws-1.3/svc/ws/ChatService?wsdl • WADL: https://cc.readytalk.com/ccws-1.3/svc/rs?_wadl
List Chats The listChats service returns all chat data for a specified meeting
Specifications SOAP Endpoint • Production URL: https://cc.readytalk.com/ccws-1.3/svc/ws/ChatService • WSDL: https://cc.readytalk.com/ccws-1.3/svc/ws/ChatService?wsdl REST Endpoint • Production URL: https://cc.readytalk.com/api/1.3/svc/rs/chats • WADL: https://cc.readytalk.com/ccws-1.3/svc/rs?_wadl • Method: GET
Input (* = Required) Parameter Explanation Constraint * id The id value of the meeting. long Response Element Explanation Constraint chatdateIso8601 The date when the message was sent, in ISO-8601 format. dateTime conferenceId The id of the conference where the chat was sent. If a meeting is integer stopped/started multiple times then a unique conferenceId is assigned to each instance of the meeting. message The message that was sent. string sender/name The person or group that sent the message. string sender/email The person or group who was the target of the message. string senderRole Sender roles listed below: string CHAIRPERSON PARTICIPANT PRESENTER sender/attendanceId The attendanceId, if any, of the sender of the message. integer sender/registrationId The registrationId, if any, of the sender of the message. long recipient/name The name, if any, of the recipient of the message. string
52
recipient/email The email, if any, of the recipient of the message. string recipientType Recipient types listed below: string EVERYONE CHAIRPERSON PRESENTER ALL_PRESENTERS PARTICIPANT_AND_PRESENTERS recipient/attendanceId The attendanceId, if any, of the recipient of the message. integer recipient/registrationId The registrationId, if any, of the recipient of the message. long tag Tag types listed below: string QUESTION ANSWERED Note: Tags are only included if the chat was flagged as an important “question” or if the flagged question was marked as “answered” by the host or presenters. Samples SOAP Request
REST Request (GET) https://cc.readytalk.com/api/1.3/svc/rs/chats?id=4548897254076495325 REST Response
54
55
Recording Services The recording service provides access to a list of recordings for an account and details about specific recordings. All calls must include authentication information in the HTTP request header, as noted previously. • WSDL: https://cc.readytalk.com/ccws-1.3/svc/ws/RecordingService?wsdl • WADL: https://cc.readytalk.com/ccws-1.3/svc/rs?_wadl List Recordings The listRecordings service returns summary information of each recording that meets the input criteria specified. Specifications SOAP Endpoint • Production URL: https://cc.readytalk.com/ccws-1.3/svc/ws/RecordingService • WSDL: https://cc.readytalk.com/ccws-1.3/svc/ws/RecordingService?wsdl REST Endpoint • Production URL: https://cc.readytalk.com/api/1.3/svc/rs/recordings • WADL: https://cc.readytalk.com/ccws-1.3/svc/rs?_wadl • Method: GET Input Parameter Explanation Constraint pagingCriteria.firstResultIndex The index of the first desired result as an integer integer Default = 0 pagingCriteria.resultCount Total results to return as an integer integer Default Note: If you need to obtain more than 500 results, you will = 25 need to make additional listRecordings calls and update Min = 5 the firstResultIndex accordingly. Max = 500 Example: A firstResultIndex of 0 and a resutCount of 10 would return your first 10 recordings. To pull over the next 10 recordings, set your firstResultIndex to 10 and leave your resultCount equal to 10. fromDate ISO 8601 formatted date/time string. When provided, string filters to return only recordings created after this date and Default = The time. earliest date Example: 2015-11-02T14:00:00.000-07:00 available Note: It’s ok to neglect the time & only include a date. toDate ISO 8601 formatted date/time string. When provided, string filters to return only recordings created before this date Default = The and time. furthest future Note: It’s okay to neglect the time & only include a date. date
56
Response
Element Explanation Constraint totalResultCount The total number of results found by the query made. integer id The unique identifier of the recording. integer title The title of the recording. string startDateIso8601 The recording start time in ISO 8601 format. dateTime endDateIso8601 The recording end time in ISO 8601 format. dateTime originalDurationInSeconds The original recording length (The edited duration can be shorter). integer registrationEnabled Boolean denoting whether the user needs to register to view the boolean recording. playbackNotificationEnabled Boolean denoting whether the chairperson will receive notification each boolean time the recording is played back. playbackCount The total number of playbacks, excluding chairperson playbacks. integer playbackUrl The link to the recording that users can access. string passcodeEnabled Boolean denoting whether a passcode is required to view the recording. boolean Samples SOAP Request
57
58
Recording Details This service retrieves all of the available details for a specified recording. Specifications SOAP Endpoint • Production URL: https://cc.readytalk.com/ccws-1.3/svc/ws/RecordingService • WSDL: https://cc.readytalk.com/ccws-1.3/svc/ws/RecordingService?wsdl REST Endpoint • Production URL: https://cc.readytalk.com/api/1.3/svc/rs/recordings/{id} • WADL: https://cc.readytalk.com/ccws-1.3/svc/rs?_wadl • Method: GET
Input (* = Required) Parameter Explanation Constraint * id The id of the recording for which details are desired. integer videoResolution The resolution to be used for the HTML embed code for the string recording if it can be embedded. Available resolutions Default = 320x240 listed below: 320x240 480x320 640x480 Response Element Explanation Constraint id The unique id of the recording. integer title The title of the recording. string startDateIso8601 The recording start time in ISO 8601 format. dateTime endDateIso8601 The recording end time in ISO 8601 format. dateTime originalDurationInSeconds The original recording length (The edited duration can be integer shorter). registrationEnabled Boolean denoting whether the user needs to register to boolean view the recording. playbackNotificationEnabled Boolean denoting whether the chairperson will receive boolean notification each time the recording is played back. playbackCount The total number of playbacks, excluding chairperson integer playbacks. playbackUrl The link to the recording that users can access. string passcodeEnabled Boolean denoting whether a passcode is required to view boolean the recording.
59
embedCode The HTML code used to embed the video in a website. string Note: Although an embed code will be returned for all recordingDetails requests, the embed code will not work properly unless the recording has been added to your ReadyTalk podcast page. Visit the ReadyTalk Support Center for more information about podcasting recordings. Samples SOAP Request
REST Request (GET) https://cc.readytalk.com/api/1.3/svc/rs/recordings/1612341?videoResolution=640x480 REST Response
61
Recording Registration Service The recording registration service provides the capability to list registrations for a recording. All calls must include authentication information in the HTTP request header, as noted previously. • WSDL: https://cc.readytalk.com/ccws-1.3/svc/ws/RecordingRegistrationService?wsdl • WADL: https://cc.readytalk.com/ccws-1.3/svc/rs?_wadl List Recording Registrations The recording registration service provides the capability to list registrations for a recording. Specifications SOAP Endpoint • Production URL: https://cc.readytalk.com/ccws-1.3/svc/ws/RecordingRegistrationService • WSDL: https://cc.readytalk.com/ccws-1.3/svc/ws/RecordingRegistrationService?wsdl REST Endpoint • Production URL: https://cc.readytalk.com/api/1.3/svc/rs/recording/registrations • WADL: https://cc.readytalk.com/ccws-1.3/svc/rs?_wadl • Method: GET
Input (* = Required)
Parameter Explanation Constraint * recordingId integer pagingCriteria.firstResultIndex The index of the first desired result as an integer integer Default = 0 pagingCriteria.resultCount Total results to return as an integer integer Default = 25 Note: If you need to obtain more than 500 results, you will Min = 5 need to make additional listRecordingRegistrations calls and Max = 500 update the firstResultIndex accordingly. Example: A firstResultIndex of 0 and a resutCount of 10 would return your first 10 recording registrants. To pull over the next 10 recording registrants, set your firstResultIndex to 10 and leave your resultCount equal to 10. fromDate ISO 8601 formatted date/time string. When provided, filters string to return only individuals who registered after this date and Default = The time. earliest date Example: 2015-11-02T14:00:00.000-07:00 available Note: It’s ok to neglect the time & only include a date.
62
Response
Element Explanation Constraint registration/id The unique id value of the viewer. integer registration/encodedId The base36 encoded form of the registration id. string lastUpdatedDate The date and time of the last update to this viewer’s information. dateTime questionId The id value of the question. long questionText The recording registration question. string value The viewers response to the recording registration question. string playback/id The id value of the viewer of the recording. integer playbackDate The date and time the individual viewed the recording. dateTime playbackDuration The amount of time playback registrant spent viewing the integer recording, in milliseconds. Samples SOAP Request
64
Error Specification Errors that occur in the Conference Center API system are specified as results composed of an error code, a message, and (when applicable) the invalid value that caused the error. All errors returned by the system will conform to the following XSD specification:
Code Each error specifies a code that contains information pertaining to the error state. The encoding format is defined using the specification below: Extended Backus-Naur: • error code = digit, { delimiter, digit }; • digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"; • delimiter = "."; Examples: • 1 • 1.2 • 2.3.2 * A table of codes and their respective messages are documented in the Error Documentation section below.
Messages Each error contains a concise, localized message describing the error state. By default, all messages are localized to English, US.
66
Invalid Value The invalid value contains the value that caused the error. This value is only supplied when it is applicable to the error condition.
Error Documentation
SOAP Errors Errors returned in SOAP are wrapped within a Fault envelope. Currently, SOAP faults contain the top-level code and message in the faultstring as well as XML within the fault detail that conforms to the errors XSD specification. Example: Meeting Not Found 1.2.1
REST Errors All errors returned in rest conform to the schema specification documented above. Additionally, each error response contains an appropriate HTTP response status code so that systems can be informed that an error occurred. Please reference the error code table above for specific HTTP status codes. Example: Meeting Not Found 1.2.1
Error Code Table The error code table below contains all codes and their respective meta-data (messages, detailed documentation, and HTTP status codes). Error Code Table: https://na32.salesforce.com/sfc/p/500000007Zge/a/38000000DCMU/JNOkU9I7h9H4wqq2u3gP2upB.KryTPhN oTZ6zt3gXj8 (Click on the link and then click the “Download” button near the bottom of the screen to view the error code table). 67
FAQ 1. If I am having issues with the API, where can I get help? • Contact ReadyTalk’s Integration Support Team at [email protected]. • Availability: Monday – Friday, 8:00AM – 5:00PM Eastern Time (USA) • Please include the following in your communication: o An in-depth description of the issue, including any applicable error codes/messages. o Include parameters, endpoints, and headers if applicable. o Include account credentials. 2. Where do I obtain an Access Number, Access Code, and Passcode? • This information is included in your welcome email after signing up for a ReadyTalk account. The Access Number is the conferencing phone number; the Access Code is the 7-digit number; and the Passcode is the 4 to 9 digit number. 3. Where can I found out more information about ReadyTalk’s features? • Here is a link to our Support Center: https://support.readytalk.com/SP/ 4. What is the Conference Center? • The ReadyTalk Conference Center is customer portal used for… o Scheduling meetings o Starting meetings o Sending invitation emails, reminder emails, and follow-up emails o Viewing registration and attendance data for both web and audio meetings o Viewing chat data, polling data, and custom survey data from past conferences o Viewing and managing recordings 5. Where can I obtain the Meeting ID? • The Meeting ID can only be found via a request to the API. The Meeting ID will be returned in the following API requests: createMeeting, listMeetings, and updateMeeting. If the meeting has already been created and it does not need updating, then utilize the listMeetings request to obtain the Meeting ID for your existing meeting. 6. What is the difference between the Audio Types? • The On-Demand Audio Type is best used when a meeting will have fewer than 150 participants. o This type is best used when you are utilizing a Pay-As-You-Go, Meeting 10, Meeting 25, or Meeting 100 subscription type. Note: Pay-As-You-Go accounts support up to 150 audio participants. Meeting accounts support 10, 25, or 100 participants respectfully. • The Operator Assisted Audio Type is best used when anticipating more than 150 participants or if you require operator assistance for your call (If you are anticipating more than 3,000 participants, please contact our support team to ensure we can accommodate your large meeting). o This type is best used when you are utilizing a Webinar 150, Webinar 500, or Webinar 3,000 subscription type.
68
Notes: • This option requires a reservation with ReadyTalk's Events Team before it can be chosen. To make a reservation, click on the Request Event Services option located on the left side of your Conference Center. • All operator-assisted event services require a five-hour turnaround time. Requests received after 12pm Mountain Time (Monday - Friday) will be processed on the next business day. • Additional features such as Broadcast Audio, Transcriptions, & Closed Captioning are available on Operator Assisted Events.
7. What is the difference between the Meeting Types? • WEB_AND_AUDIO o Choose this option if you desire to host a meeting that includes both visual and audio content. • AUDIO_ONLY o Choose this option if you desire to host a meeting that includes audio content over the telephone only. • WEB_ONLY o Choose this option if you desire to host a meeting that includes visual content only or if you desire for all participants to join the audio portion of your meeting using their computer microphone and speaker instead of their telephone.
8. What is the difference between the Registration Types? • ReadyTalk offers two registration types, REG_AT_TIME and PRE_REG, and a few variations on those types. o REG_AT_TIME_AUTOMATIC_CONFIRMATION_NO_NOTIFICATION This registration type allows individuals to fill out a registration form at the time of the conference to join the live meeting. Upon submitting the form, registrants are immediately brought into the live conference. This type is best used when the host of the meeting does not want individuals registering ahead of time. Since registration is not taken until the start time of the meeting, notification emails cannot be sent to the host after an individual registers for the meeting. In addition, since individuals are placed directly into the live meeting after registering, the host cannot decline an individual’s registration. o PRE_REG_AUTOMATIC_CONFIRMATION_NO_NOTIFICATION This registration type allows individuals to register before the meeting start time (Individuals can still register during the live conference). After an individual registers, they will receive a unique join meeting URL (Either via a ReadyTalk email or via an alternate source that you manage through your program). This registration type is the most common type used as it allows you to easily take registration through a third party system using a createRegistration API request. This type will not send a notification email to the host when someone registers.
69
o PRE_REG_AUTOMATIC_CONFIRMATION_WITH_NOTIFICATION This is a variation of the PRE_REG type that will notify the host of the meeting via email when an individual registers. o PRE_REG_MANUAL_CONFIRMATION_WITH_NOTIFICATION This is a variation of the PRE_REG type that requires the host to log into their ReadyTalk Conference Center and manually approve each registrant if registration is taken via a ReadyTalk Registration Form. If a createRegistration API request is submitted instead of having registrants utilize a ReadyTalk Registration Form, the API assumes registration is approved and will confirm the individual without any additional action needed from the host of the meeting.
9. How can I obtain more than 500 results? • Most API requests only support 500 results. If more than 500 results need to be returned, then additional requests must be made using pagingCriteria. Example: A firstResultIndex of 0 and a resutCount of 500 would return your first 500 results. To pull over the next 500 results, set your firstResultIndex to 500 and leave your resultCount equal to 500.
10. Why is my API request not working? General Expected Errors • Calls will return an error if the passed authentication credentials are invalid. • If request parameters are invalid (formatting/type) then a validation error is returned. • Invalid input parameters will result in a validation error being returned. • Missing required input parameters will result in a validation error being returned. • Blank values for required parameters will result in a validation error being returned. • Improperly formatted endpoints or pointing to the incorrect endpoint will result in an error. • Review the Error Specification section, the Error Documentation section, or the Error Code Table for more details.
11. How do I schedule a Self-Serve Broadcast Audio meeting via the API? • Unfortunately, at this time, it is not possible to schedule an SSBA meeting entirely through the API; however, you can create a normal meeting with an On-Demand Audio Type using the API and then manually log into your Conference Center, edit the newly created meeting, and enable the SSBA feature. • Visit the ReadyTalk Support Center for more information about the SSBA feature. Note: The Self-Serve Broadcast Audio meeting is currently only available for customers on a Webinar 150, 500, or 3,000 subscription.
12. How can I launch a Scheduled meeting using the API? • If you would like to obtain a unique link that will allow the host of the meeting to launch a specific scheduled meeting, you can create one using the static link below. Simply use the meetingId (Returned in a 70
createMeeting response or a listMeeting response) and use that to make a meetingDetails call. Take the access code, the conferencing phone number, the passcode, and the encodedId (Returned in the meetingDetails call) and add that to the following static URL. When clicked, this URL will launch the scheduled meeting associated with the encodedId. • https://core.readytalk.com/interface/applet.jsp?ac={accessCode}&tf={phone}&pin={passcode}&ev={e ncodedId}
13. Can participants login without having to enter their email address as confirmation? • When registrants click on their Join Meeting URL, they are prompted to verify their email address before they are brought into the live conference. This is done as an additional security measure to ensure that Join Meeting URLs are not shared. This security step can be bypassed if desired. To do so, append &email= to the end of each registrants unique Join Meeting URL and then add their email address (This option is only possible when you are sending out personal emails and the sendConfirmationEmail value is set to “false”. Example: https://cc.readytalk.com/partlogin/[email protected] Note: By bypassing this security measure, anyone who has access to a unique Join Meeting URL can access the meeting.
14. Can I obtain calendar files URLs for each of my registrants? • Add to Calendar URL’s are not included in API responses; however… o If your sendConfirmationEmail value is “true”, then Add to Calendar URL’s will automatically be included on the emails sent out of the ReadyTalk system. o If the sendConfirmationEmail value is “false”, you are sending out your own personal emails, and you would like to include Add to Calendar links in your personal emails, you can take each registrant’s unique encodedId that is returned in the createRegistration response and append that to the following static URL’s to create unique Add to Calendar URL’s for each registrant. Outlook Add to Calendar: https://cc.readytalk.com/cc/schedule/iCalCreation.do?regId={encodedId} Google Add to Calendar: https://cc.readytalk.com/gcal/r/{encodedId}
15. What are campaigns & how do I set one up? • The ReadyTalk Campaign feature allows you to create multiple registration URLs and then see how many individuals click-to-view and/or register using a particular URL. This feature is beneficial when trying to determine which registration source is the most successful.
• Campaign URLs cannot be created using the API and must be setup within your ReadyTalk Conference Center. For more information on creating a campaign, visit the ReadyTalk Support Center. • You can tie a specific campaign back to a registrant when using a createRegistration call and a campaignId (Campaign ID’s can be obtained using a meetingDetails API request). • To view the number of hits or the number of registrations for each campaign URL, navigate to the home screen of your Conference Center, click on the title of your meeting, and then click on the “Campaign Report” link located below the “Reports” section.
71
16. When I send a request to the API, I receive the following error “Invalid account credentials”. Why is this happening?
• In most cases, this issue is caused by improper syntax. Please review the Authentication section of this guide for more information on how to pass in account credentials within your API request. • If you are attempting to access the sandbox environment and your account is less than 24 hours old, you will receive this error. It takes 24 hours for your account to be setup with access to the sandbox environment. This process is automatic and does not need to be requested. • In extremely rare instances, some accounts may not have access to the sandbox environment even after 24 hours. If you believe that you fall into this scenario, please contact ReadyTalk’s Integration Support Team at [email protected]. o Availability: Monday – Friday, 8:00AM – 5:00PM Eastern Time (USA) o Please include the following in your communication: An in-depth description of the issue, including any applicable error codes/messages. Include parameters, endpoints, and headers if applicable. Include account credentials.
17. Where can I obtain a Broadcast Audio Code? Broadcast Audio Codes, are only available for Operator Assisted Events. Operator Assisted Events require a reservation with ReadyTalk's Events Team. To make a reservation, click on the Request Event Services option located on the left side of your Conference Center. All operator-assisted event services require a five-hour turnaround time. Requests received after 12pm Mountain Time (Monday - Friday) will be processed on the next business day. Additional features such as Broadcast Audio, Transcriptions, & Closed Captioning are available on Operator Assisted Events.
72