Gather Speech

Gather Speech records are generated when you are using the <Gather> verb with Speech input type. Those records are hosted with CPaaS and are available for you to retrieve. The Gather Speech records list resource represents a set of an account’s Gather Speech records.

The Gather Speech API endpoint supports JSON output only.

Gather Speech Resource URI

/2012-04-24/Accounts/{AccountSid}/Gathers/Speech/{GatherSid}

Resource Properties

Property Description

Property	Description
sid	A string that uniquely identifies this record.
date_created	The date this record was created.
account_sid	The unique id of the Account that created this record.
org_sid	The unique id of the Organization which belongs to the Account.
call_sid	The unique id of the call during which gathering of the call was made.
provider	Configured ASR provider to use.
language	Configured language for the ASR operation.
preTimeout	Configured preTimeout. The amount of time to wait for a user to speak before timing out.
postTimeout	Configured postTimeout. The amount of time to wait for the next word to be spoken by the user before timing out.
hints	Configured hint words that are passed to the ASR engine.
action_on_empty_result	Configured value for this parameter. Whether to invoke an action if the result is empty.
duration	The time it took in seconds to recognize the speech.
status	The status of the Gather Verb. Values can be `completed` or `failed`.
reason	The reason why the Gather failed.
api_version	The API version in use during the recording.
uri	The URI for this Gather Speech record, relative to `https://$DOMAIN/restcomm`.

sid

A string that uniquely identifies this record.

date_created

The date this record was created.

account_sid

The unique id of the Account that created this record.

org_sid

The unique id of the Organization which belongs to the Account.

call_sid

The unique id of the call during which gathering of the call was made.

provider

Configured ASR provider to use.

language

Configured language for the ASR operation.

preTimeout

Configured preTimeout. The amount of time to wait for a user to speak before timing out.

postTimeout

Configured postTimeout. The amount of time to wait for the next word to be spoken by the user before timing out.

hints

Configured hint words that are passed to the ASR engine.

action_on_empty_result

Configured value for this parameter. Whether to invoke an action if the result is empty.

duration

The time it took in seconds to recognize the speech.

status

The status of the Gather Verb. Values can be completed or failed.

reason

The reason why the Gather failed.

api_version

The API version in use during the recording.

uri

The URI for this Gather Speech record, relative to https://$DOMAIN/restcomm.

Supported Operations

HTTP GET. Returns the representation of a Gather Speech resource, including the properties above.

Listing a Singe Gather Speech Record

curl -X GET https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Gathers/Speech/GAc377eb0e657e415383de087ab38797db  \
   -u 'YourAccountSid:YourAuthToken'

const request = require('request');

// Provide your Account Sid and Auth Token from your Console Account page
const ACCOUNT_SID = 'my_ACCOUNT_SID';
const AUTH_TOKEN = 'my_AUTH_TOKEN';

request({
      method: 'GET',
      url: 'https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Gathers/Speech/GAc377eb0e657e415383de087ab38797db',
      auth: { 'user': ACCOUNT_SID, 'pass': AUTH_TOKEN }
   },
   function (error, response, body) {
      // Add your business logic below; status can be found at 'response.statusCode' and response body at 'body'
      ...
   }
);

from http.client import HTTPSConnection
from base64 import b64encode

# Provide your Account Sid and Auth Token from your Console Account page
ACCOUNT_SID = 'my_ACCOUNT_SID'
AUTH_TOKEN = 'my_AUTH_TOKEN'

userAndPass = b64encode(bytes(ACCOUNT_SID + ':' + AUTH_TOKEN, 'utf-8')).decode("ascii")
headers = { 'Authorization' : 'Basic %s' %  userAndPass }

conn = HTTPSConnection('mycompany.restcomm.com')
conn.request("GET", '/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Gathers/Speech/GAc377eb0e657e415383de087ab38797db',
      headers=headers)
res = conn.getresponse()

# Add your business logic below; status can be found at 'res.status', reason at 'res.reason' and response body can be retrieved with res.read()
...

import java.net.URL;
import javax.net.ssl.HttpsURLConnection;
import java.io.*;
import java.util.Base64;

public class JavaSampleClass {
   // Provide your Account Sid and Auth Token from your Console Account page
   public static final String ACCOUNT_SID = "my_ACCOUNT_SID";
   public static final String AUTH_TOKEN = "my_AUTH_TOKEN";


   public static void main(String[] args) throws Exception {
      String userAndPass = ACCOUNT_SID + ':' + AUTH_TOKEN;
      String encoded = Base64.getEncoder().encodeToString(userAndPass.getBytes());

      URL url = new URL("https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Gathers/Speech/GAc377eb0e657e415383de087ab38797db");
      HttpsURLConnection conn = (HttpsURLConnection)url.openConnection();
      conn.setRequestProperty("Authorization", "Basic " + encoded);
      conn.setRequestMethod("GET");

      // Add your business logic below; response code can be obtained from 'conn.getResponseCode()' and input stream from 'conn.getInputStream()'
      ...
  }
}

Example Response

{
  "sid": "GAc377eb0e657e415383de087ab38797db",
  "date_created": "2021-03-09T12:03:00.787Z",
  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "org_sid": "ORfe81fe8a3d5f4d5391e901db0bf5755d",
  "call_sid": "IDbb44ef8c2ebf4d4599d0378a2a8a2ea8-CAd9e08ede8b604e739ba7d0bd477fdf49",
  "preTimeout" : 5,
  "postTimeout" : 5,
  "actionOnEmptyResult" : "false",
  "status": "completed",
  "hints" : "hello world",
  "reason" :,
  "provider" : "google",
  "language" : "en-US",
  "duration": 3,
  "api_version": "2012-04-24",
  "uri": "/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Gathers/Speech/GAc377eb0e657e415383de087ab38797db.json"
}

Gather Speech List Resource

Gather Speech List Resource URI

/2012-04-24/Accounts/{AccountSid}/Gathers/Speech

Supported Operations

HTTP GET

Returns the list representation of all the Gather Speech records resources for a given account, including the properties above.

Getting a List of Gather Speech Records

You can list Gather Speech records by making the following API request:

curl -X GET https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Gathers/Speech  \
   -u 'YourAccountSid:YourAuthToken'

const request = require('request');

// Provide your Account Sid and Auth Token from your Console Account page
const ACCOUNT_SID = 'my_ACCOUNT_SID';
const AUTH_TOKEN = 'my_AUTH_TOKEN';

request({
      method: 'GET',
      url: 'https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Gathers/Speech',
      auth: { 'user': ACCOUNT_SID, 'pass': AUTH_TOKEN }
   },
   function (error, response, body) {
      // Add your business logic below; status can be found at 'response.statusCode' and response body at 'body'
      ...
   }
);

from http.client import HTTPSConnection
from base64 import b64encode

# Provide your Account Sid and Auth Token from your Console Account page
ACCOUNT_SID = 'my_ACCOUNT_SID'
AUTH_TOKEN = 'my_AUTH_TOKEN'

userAndPass = b64encode(bytes(ACCOUNT_SID + ':' + AUTH_TOKEN, 'utf-8')).decode("ascii")
headers = { 'Authorization' : 'Basic %s' %  userAndPass }

conn = HTTPSConnection('mycompany.restcomm.com')
conn.request("GET", '/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Gathers/Speech',
      headers=headers)
res = conn.getresponse()

# Add your business logic below; status can be found at 'res.status', reason at 'res.reason' and response body can be retrieved with res.read()
...

import java.net.URL;
import javax.net.ssl.HttpsURLConnection;
import java.io.*;
import java.util.Base64;

public class JavaSampleClass {
   // Provide your Account Sid and Auth Token from your Console Account page
   public static final String ACCOUNT_SID = "my_ACCOUNT_SID";
   public static final String AUTH_TOKEN = "my_AUTH_TOKEN";


   public static void main(String[] args) throws Exception {
      String userAndPass = ACCOUNT_SID + ':' + AUTH_TOKEN;
      String encoded = Base64.getEncoder().encodeToString(userAndPass.getBytes());

      URL url = new URL("https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Gathers/Speech");
      HttpsURLConnection conn = (HttpsURLConnection)url.openConnection();
      conn.setRequestProperty("Authorization", "Basic " + encoded);
      conn.setRequestMethod("GET");

      // Add your business logic below; response code can be obtained from 'conn.getResponseCode()' and input stream from 'conn.getInputStream()'
      ...
  }
}

Example Response

{"page":0,"num_pages":0,"page_size":50,"total":34,"start":"0","end":"34","uri":"/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Gathers/Speech","first_page_uri":"/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Gathers/Speech?Page=0&PageSize=50","previous_page_uri":"null","next_page_uri":"null","last_page_uri":"/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Gathers/Speech?Page=0&PageSize=50","gathers":
    [
        {
          "sid": "GAc377eb0e657e415383de087ab38797db",
          "date_created": "2021-03-09T12:03:00.787Z",
          "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
          "org_sid": "ORfe81fe8a3d5f4d5391e901db0bf5755d",
          "call_sid": "IDbb44ef8c2ebf4d4599d0378a2a8a2ea8-CAd9e08ede8b604e739ba7d0bd477fdf49",
          "duration": 15,
          "preTimeout" : 5,
          "postTimeout" : 5,
          "actionOnEmptyResult" : "false",
          "status": "completed",
          "hints" : "hello world",
          "reason" :,
          "provider" : "google",
          "language" : "en-US",
          "api_version": "2012-04-24"
          "uri": "/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Gathers/Speech/GAc377eb0e657e415383de087ab38797db.json"
        },
        ...

    ]
}

List Filter

HTTP GET

The following GET query string parameters allow you to limit the list returned.

The query parameters are case-sensitive.

Request Parameters

Parameter	Description
DateCreated	Only show gather Speech records that started on this date/time or later, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32). If you want to omit the time, YYYY-MM-DD (for example 2018-10-05). If only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in the UTC timezone. A 400 response will be returned if the syntax is invalid.
CallSid	Only show gather speech records generated by the call with this corresponding Sid.

Parameter

Description

DateCreated

Only show gather Speech records that started on this date/time or later, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32). If you want to omit the time, YYYY-MM-DD (for example 2018-10-05). If only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in the UTC timezone. A 400 response will be returned if the syntax is invalid.

CallSid

Only show gather speech records generated by the call with this corresponding Sid.

Filtering by CallSid Parameter

The example below will return Gather Speech records that have been initiated from a specific CallSid.

curl -X GET https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Gathers/Speech?CallSid=IDbb44ef8c2ebf4d4599d0378a2a8a2ea8-CAd9e08ede8b604e739ba7d0bd477fdf49  \
   -u 'YourAccountSid:YourAuthToken'

const request = require('request');

// Provide your Account Sid and Auth Token from your Console Account page
const ACCOUNT_SID = 'my_ACCOUNT_SID';
const AUTH_TOKEN = 'my_AUTH_TOKEN';

request({
      method: 'GET',
      url: 'https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Gathers/Speech?CallSid=IDbb44ef8c2ebf4d4599d0378a2a8a2ea8-CAd9e08ede8b604e739ba7d0bd477fdf49',
      auth: { 'user': ACCOUNT_SID, 'pass': AUTH_TOKEN }
   },
   function (error, response, body) {
      // Add your business logic below; status can be found at 'response.statusCode' and response body at 'body'
      ...
   }
);

from http.client import HTTPSConnection
from base64 import b64encode

# Provide your Account Sid and Auth Token from your Console Account page
ACCOUNT_SID = 'my_ACCOUNT_SID'
AUTH_TOKEN = 'my_AUTH_TOKEN'

userAndPass = b64encode(bytes(ACCOUNT_SID + ':' + AUTH_TOKEN, 'utf-8')).decode("ascii")
headers = { 'Authorization' : 'Basic %s' %  userAndPass }

conn = HTTPSConnection('mycompany.restcomm.com')
conn.request("GET", '/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Gathers/Speech?CallSid=IDbb44ef8c2ebf4d4599d0378a2a8a2ea8-CAd9e08ede8b604e739ba7d0bd477fdf49',
      headers=headers)
res = conn.getresponse()

# Add your business logic below; status can be found at 'res.status', reason at 'res.reason' and response body can be retrieved with res.read()
...

import java.net.URL;
import javax.net.ssl.HttpsURLConnection;
import java.io.*;
import java.util.Base64;

public class JavaSampleClass {
   // Provide your Account Sid and Auth Token from your Console Account page
   public static final String ACCOUNT_SID = "my_ACCOUNT_SID";
   public static final String AUTH_TOKEN = "my_AUTH_TOKEN";


   public static void main(String[] args) throws Exception {
      String userAndPass = ACCOUNT_SID + ':' + AUTH_TOKEN;
      String encoded = Base64.getEncoder().encodeToString(userAndPass.getBytes());

      URL url = new URL("https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Gathers/Speech?CallSid=IDbb44ef8c2ebf4d4599d0378a2a8a2ea8-CAd9e08ede8b604e739ba7d0bd477fdf49");
      HttpsURLConnection conn = (HttpsURLConnection)url.openConnection();
      conn.setRequestProperty("Authorization", "Basic " + encoded);
      conn.setRequestMethod("GET");

      // Add your business logic below; response code can be obtained from 'conn.getResponseCode()' and input stream from 'conn.getInputStream()'
      ...
  }
}

Example Response

{"page":0,"num_pages":0,"page_size":50,"total":34,"start":"0","end":"34","uri":"/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Gathers/Speech","first_page_uri":"/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Gathers/Speech?Page=0&PageSize=50","previous_page_uri":"null","next_page_uri":"null","last_page_uri":"/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Gathers/Speech?Page=0&PageSize=50","gather":
    [
        {
          "sid": "GAc377eb0e657e415383de087ab38797db",
          "date_created": "2021-03-09T12:03:00.787Z",
          "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
          "org_sid": "ORfe81fe8a3d5f4d5391e901db0bf5755d",
          "call_sid": "IDbb44ef8c2ebf4d4599d0378a2a8a2ea8-CAd9e08ede8b604e739ba7d0bd477fdf49",
          "duration": 15,
          "preTimeout" : 5,
          "postTimeout" : 5,
          "actionOnEmptyResult" : "false",
          "status": "completed",
          "hints" : "yes no",
          "reason" :,
          "provider" : "google",
          "language" : "en-US",
          "api_version": "2012-04-24"
          "uri": "/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Gathers/Speech/GAc377eb0e657e415383de087ab38797db.json"
        },
        ...

    ]
}

Paging Information

The Gather Speech API request supports standard paging information. For more details, please visit the Paging Information documentation.