Voicemail Endpoint

In this guide, you will learn how to create and configure a Voicemail endpoint. A Voicemail endpoint can be used together with an application to record and playback voicemail messages.

I. Create Voicemail Endpoint Using REST API

In this section, we will go over creating a Voicemail endpoint using the REST API.

Form a POST request and include at least the voicemail endpoint type in the request body. Refer to the Create Endpoint section of the Core API Reference for a list of the other fields that can be added at the time of creation.

curl -X POST \
'https://api.carrierx.com/core/v2/endpoints' \
-H 'Content-Type: application/json' \
--data-binary '{"type": "voicemail", "name": "voicemail"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 status code and the created endpoint body data in JSON format:

{
    "addresses": [],
    "attributes": {},
    "capacity": 0,
    "endpoint_sid": "7bbb5255-234f-4288-a80d-c8b99eecad0d",
    "name": "voicemail",
    "out_sip_password": null,
    "out_sip_username": null,
    "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
    "properties": {},
    "transformations": [],
    "type": "voicemail",
    "voip_token": null
}

As you can see, the endpoint properties are not set by default and must be set manually. Refer to the next steps for more information about this.

II. Create Container

In this section, we will create a container. This container will store your greeting file and future voicemail messages.

In the left-side menu click Storage and then Containers:

Click Container

Click Add New Container:

Click Add

Enter a friendly name for the new container that is used for internal reference. Enter integer values for Quota Bytes and Quota Files.

If you leave the quota fields blank, the container size and file number will not be limited and can expand to take the entire storage available to you.

Change Container Properties

Click Add Container when finished:

Save Container

III. Upload Greeting File

In this section, we will upload a greeting file. This audio file will be used as a greeting for all voicemail messages.

In the left-side menu click Storage and then Files:

Click Files

Click Add New File:

Add New File

Enter the File Name (you will use it to distinguish this file from the other ones), select the previously created container, choose to publish file as file_sid, and set the File Type to audio. Browse for the audio file on your computer.

Click Add File when ready:

File Properties

The file will be uploaded and associated with the container. When you click the file in the list, you will see its properties. Note the Publish URI value, which is publicly accessible link to the file. You will need it at the next step.

File URL

IV. Change Voicemail Endpoint Properties

After the endpoint is created, you must set some of the properties, specific to voicemail endpoint object. These properties include:

Send the following PATCH request to set the properties:

curl -X PATCH \
'https://api.carrierx.com/core/v2/endpoints/7bbb5255-234f-4288-a80d-c8b99eecad0d' \
-H 'Content-Type: application/json' \
--data-binary '{"properties": {"container_sid": "78caeae7-e256-4fca-a33e-89ba04ac6b2f", "greeting": "https://storage.carrierx.com/f/96df5d4f-c6a2-4d5e-a43c-c2cbcb004ed3", "callback_method": "POST", "callback_url": "http://your-website.com/your-app"}}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 status code and the altered endpoint body data with the properties set in JSON format:

{
    "addresses": [],
    "attributes": {},
    "capacity": 0,
    "endpoint_sid": "7bbb5255-234f-4288-a80d-c8b99eecad0d",
    "name": "voicemail",
    "out_sip_password": null,
    "out_sip_username": null,
    "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
    "properties": {
        "callback_method": "POST",
        "callback_url": "http://your-website.com/your-app",
        "container_sid": "78caeae7-e256-4fca-a33e-89ba04ac6b2f",
        "greeting": "https://storage.carrierx.com/f/96df5d4f-c6a2-4d5e-a43c-c2cbcb004ed3",
    },
    "transformations": [],
    "type": "voicemail",
    "voip_token": null
}

V. Use Transcriptions

When the messages are recorded, the Voicemail endpoint will create transcriptions for the recorded messages.

When the transcription is ready, the Voicemail endpoint will submit it to the http://your-website.com/transcriptions address with a POST request. This request will contain the transcription text together with the following data in the request body:

{
    "AccountSid": "",
    "ApiVersion": "2.0",
    "CallSid": "4bc41f6e-f46d-4ce9-9ee1-70ff34d44922",
    "CallStatus": "",
    "Direction": "inbound",
    "From": "17605692222",
    "OriginalFrom": "+17605692222",
    "OriginalTo": "23372337",
    "RecordingFileSid": "ea662226-9f71-44fe-858f-f8b624034974",
    "RecordingUrl": "https://storage.carrierx.com/f/ea662226-9f71-44fe-858f-f8b624034974",
    "timestamp": 1595329919,
    "To": "23372337",
    "TranscriptionSid": "cac8582f-db8a-4c4d-82e5-3e8026435a54",
    "TranscriptionStatus": "completed",
    "TranscriptionText": "This is a transcribed voicemail message",
    "TranscriptionUrl": ""
}

The following attributes are included:

Attribute Data Type Description
AccountSid string The identifier of the account used to accept the call.
ApiVersion string The API version used to accept the call and create the transcription.
CallSid string The identifier of the call that was recorded.
CallStatus string The status of the call.
Direction string The direction of the call related to the Voicemail endpoint.
From string The incoming call number.
OriginalFrom string The incoming call number before any transformations were applied.
OriginalTo string The outgoing call number before any transformations were applied.
RecordingFileSid string The identifier of the message recording that was used to create the transcription.
RecordingUrl string The publicly accessible URL of the message recording.
timestamp integer The UNIX timestamp of the moment when the transcription was completed.
To string The destination call number.
TranscriptionSid string The identifier of the transcription file.
TranscriptionStatus string The status of the transcription.
TranscriptionText string The complete text of the message transcription.
TranscriptionUrl string The publicly accessible URL of the transcription.

VI. Set Custom Greetings

By default, the Voicemail endpoint will use the greeting specified in the properties.greeting attribute for all the incoming calls. Based on the incoming call data, dedicated greetings can be specified for calls with certain data (e.g., a specific phone number).

At the beginning of each call the Voicemail endpoint can pass the control over the call flow to your application using a method similar to the FlexML Redirect verb.

Below is the example of what the data sent to your application might look like (refer to the description of the parameters at Step V):

{
    "AccountSid":"",
    "ApiVersion":"2.0",
    "CallerName":"",
    "CallSid": "4bc41f6e-f46d-4ce9-9ee1-70ff34d44922",
    "CallStatus":"",
    "Direction":"inbound",
    "From": "17605692222",
    "OriginalFrom": "+17605692222",
    "OriginalTo": "23372337",
    "timestamp": 1595329919,
    "To": "23372337"
}

At the very basic scenario your application should simply search for a greeting file using the data received (e.g., select a custom greeting file for the "From" phone number received in the JSON). Then the call flow control must be returned back to the Voicemail endpoint together with the greeting URL passed as the gr parameter in its query string. The value of this parameter is set to the URL of the custom greeting file, e.g.: ?gr=http%3A%2F%2Fyour-storage.com%2Fyour-greeting.mp3

For example, if you use FlexML for your application, the following code will turn over the call flow control back to the Voicemail endpoint together with the URL of the custom greeting file, which will be used for the current call:

<Response>
    <Redirect>https://voicemail.carrierx.com/?gr=http%3A%2F%2Fyour-storage.com%2Fyour-greeting.mp3</Redirect>
</Response>

You need to replace the https://voicemail.carrierx.com/ URL with the one from which your application received the initial request from the Voicemail endpoint, and http://your-storage.com/your-greeting.mp3 is the URL of your greeting file. FlexML will automatically include the initial data received from the Voicemail endpoint into the response when you use the Redirect verb.

If the gr parameter is missing, or no media file can be found at the received URL, Voicemail endpoint will fall back to the default greeting specified in the properties.greeting attribute.

VII. Next Steps

You have created a Voicemail endpoint! The next steps before you can start using the created endpoint, might be the following: