Uploading Audio Messages
From Videntity Documentaion Wiki
Videntity gives you a way of customizing specific messages that are played to your user base when they receive phone calls. Currently their are only two static messages (that don't involve transactions) that are recordable: enrollment messages, and introduction messages. These API messages are thought of as static messages, meaning that these messages will not be changed once set. Thus, your entire user base will hear these messages. You can, However, change your static API messages by resubmitting them. Resubmitting your messages will write over your currently set message and you will know longer be able to use it. There are additional dynamic messages that can be uploaded for use in transactions. Transaction messages are more frequently set and usually pertain to a single transaction with multiple receivers. Therefore, transaction messages can be found in the API Transactions section
Contents |
Enrollment Messages
The enrollment message is played before a user is prompted to enroll in our Videntity phone system. The enrollment message gives the API user a chance to introduce themselves and tell the enrollee what is about to happen and why it is about to happen.
An example enrollment message:
For your protection, Your Hospital has initiated, Videntity, a new identity verification system for phone-based access to your medical information. Videntity allows providers to securely communicate with you, keeping you more informed about your medical affairs. Upon enrollment, both a pin and your voice will be required to access your account by phone. A secret phrase in your own voice will also be recorded and played back to you to ensure the authenticity of the call. This new system highlights our commitment to your privacy and your account security. We urge you to take a moment now to enroll into our new telephone security system.
Your enrollment message may be sent to the Videntity server in one of two forms. You may either send the enrollment message as text (similar to above) or you may make an audio recording and upload it. If you submit your message as text only we will convert it to speech for the user to hear at the time of the phone call. While this is the simplest option it doesn't typically sound well and can be hard for the user to understand. So, we recommend that you record and upload your enrollment message and all other messages. If you prefer your enrollment message to be recorded to match our in house voice, for a fee, we can record and upload your enrollment messages for you. This usually takes no more then a few days.
To submit your enrollment message send a multipart form POST to the Static Upload Enroll Message method:
https://videntity.com/static_messages/upload_enroll_message
For a detailed description of the form fields please see the Static Upload Enroll Message method section.
Introduction Messages
The introduction message is played right after the user answers the phone and right before the user verifies their voice when using the Videntity phone system. The introduction message gives the API user a chance to introduce themselves at the beginning of the phone call. The introduction messages is typically just the name of the API User.
An example introduction message:
My Hospital
or
My Medical Record Website
Your introduction message may be sent to the Videntity server in one of two forms. You may either send the introduction message as text (similar to above) or you may make an audio recording and upload it. If you submit your message as text only we will convert it to speech for the user to hear at the time of the phone call. While this is the simplest option it doesn't typically sound well and can be hard for the user to understand. So, we recommend that you record and upload your introduction message and all other messages. If you prefer your introduction message to be recorded to match our in house voice, for a fee, we can record and upload your introduction messages for you. This usually takes no more then a few days.
To submit your enrollment message send a multipart form POST to the Static Upload Intro Message method:
https://videntity.com/static_messages/upload_intro_message
For a detailed description of the form fields please see the Static Upload Intro Message method section.
Notification Messages
Your first step in creating a transaction is creating your notification message. The notification messages is the main message of a phone call, it tells the person who is being called and what the reason of the call is for.
One example of a notification message would be a physician asking for a medical information response from his patient:
Please test your blood glucose level every four hours. If your blood sugar is 240mg/ml or greater, you should also check your urine for ketones.
Another example would be a physcian request access to a patients online medical inforamtion:
SENDER would like to access your online medical record.
Request: Notification Messages
Either message example could be sent via a text message or a phone call. So, when submitting your notification message we give you the option of submitting a text string or uploading an audio file to be used as your transaction message.
To create a transaction message send a multiform POST to the Transaction Upload Notification Message method
https://videntity.com/transaction/upload_notification_message
with the multipart form field parameters:
session_key (required): key to your current session. Your session key is given to you in response to your login request.
sms_text (optional): text message to be sent out. Text message length must not exceed 160 characters.
phone_text (optional): text message that is converted into speech hat is played as the main message of a phone transaction.
The phone_text parameter replaces phone_audio if phone_audio is not present.
phone_audio (optional): audio file that is played as the main message of a phone transaction
Response: Notification Messages
Once your notification message request has been submitted the Videntity server will update its database and create a notification message reference known as the notification message id (notification_message_id). This id will be given to you in the response XML as:
<?xml version="1.0" encoding="utf-8"?>
<response api_method="transaction/upload_notification_message">
<status>SUCCESS</status>
<api_tx_number>182737893</api_tx_number>
<detail>your file uploaded successfully</detail>
<response_name_value>
<notification_message_id>32</notification_message_id>
</response_name_value>
<timestamp>2008-09-30 15:56:42</timestamp>
</response>
with the notification_message_id as a child node to the response_name_value element.
Inquiry Messages
Your next step in creating a transaction is creating your inquiry message. The inquiry messages is used as a way of asking the receiver of the phone call for a response back.
If we follow our previous notification message example, one example of a transaction message would be a physician asking for a medical information response from his patient:
To give a spoken report to your physician of your current blood glucose level, weight, and any problems you are having please press 1 now.
Another example would be a physician request access to a patients online medical information:
To allow access to your online medical record Press 1, Press 2 to deny access to your online medical record. For more information please contact Your Doctor at 3042912480.
Your inquiry message is not a required message in your transaction. If left out of the transaction the Videntity call server will not ask the phone call receiver for a response. The server will just call and verify the identity of the receiver and play the notification message (as a notification) and then hang up. However, if you include the inquiry message in your transaction the Videntity server will expect some form of response from the phone call receiver. The response of a phone call receiver can come in two forms via the phone keypad input or by the phone call receiver recording an audio message of the phone call. The response type is set in the response_type form field as either keypad or audio.
Keypad Response
To tell the Videntity server that you would like the receiver of the phone call to respond with a keypad response, set the response_type form field as:
keypad
This tells the Videntity server that the user is going to respond by pressing the digits on the keypad. So your inquiry message is going to have to tell the user what the keypad numbers mean and who to call for additional information. As in the medical record example:
To allow access to your online medical record Press 1, Press 2 to deny access to your online medical record. For more information please contact Your Doctor at 3042912480.
Once the user hears the inquiry message any key that they press will be recorded. Once the call is complete the Videntity server will send a POST to your API client webserver cgi script that we give you.
Audio Response
To tell the Videntity server that you would like the receiver of the phone call to respond with an audio response, set the response_type form field as:
audio
This tells the Videntity server that the user is going to respond by recording an audio message over the phone. To start the recording process the receiver of the phone call will have to press 1 on the keypad. So your inquiry message is going to have to tell the user to press one to record the message. As in the the audio response to the physician:
To give a spoken report to your physician of your current blood glucose level, weight, and any problems you are having please press 1 now.
Once the receiver of the phone call hears the inquiry message and presses one, they will be prompt to record a message and then press the pound key. Upon pressing the pound key they will hear their recorded message. If the recorded message is satisfactory they will then be prompt to press one too complete the transaction or press 2 to rerecord the message. If 2 is pressed on the phone keypad they will be asked to record the message again just as they did before, and the cycle continues till they are satisfied with their recorded message. If 1 is pressed after recording the message the transaction is completed and the line will be hung up. Once the call is complete the Videntity server will send a POST to your API client webserver cgi script that we give you.
Request: Inquiry Messages
Inquiry messages can be sent via a phone call only. We currently do not support text message authorizations, because our text message capabilities currently only support outbound messaging only. Therefore we have no way of receiving a text message response. So, when submitting your inquiry message you only have the option of submitting a text string or uploading an audio file to be used during the phone call.
To create a inquiry message send a multiform POST to the Transaction Upload Inquiry Message method
https://videntity.com/transaction/upload_inquiry_message
with the multipart form field parameters:
session_key (required): key to your current session. Your session key is given to you in response to your login request.
phone_text (optional): text message that is converted into speech hat is played as the authorization message of a phone transaction.
The phone_text parameter replaces phone_audio if phone_audio is not present.
phone_audio (optional): audio file that is played as the authorization message of a phone transaction
authorization_response (required): type of response that the phone user will respond with.
Authorization response options are keypad and audio.
keypad: the receiver of the phone call will respond by pressing the phone keypad
audio: the receiver of the phone call will respond by recording an audio message
Response: Inquiry Messages
Once your inquiry message request has been submitted the Videntity server will update its database and create a inquiry message reference known as the inquiry message id (inquiry_message_id). This id will be given to you in the response XML as:
<?xml version="1.0" encoding="utf-8"?>
<response api_method="transaction/upload_inquiry_message">
<status>SUCCESS</status>
<api_tx_number>182737893</api_tx_number>
<detail>your file uploaded successfully</detail>
<response_name_value>
<inquiry_message_id>55</inquiry_message_id>
</response_name_value>
<timestamp>2008-09-30 15:56:42</timestamp>
</response>
with the inquiry_message_id as a child node to the response_name_value element.
