Inbound Phone Number Report Resource

Overview

(information)

Legal notice

Not a HIPAA Eligible Service

Voice Insights Reports API is not a HIPAA Eligible Service and should not be used in workflows that are subject to HIPAA.

An Inbound Phone Number Report aggregates Voice Insights metrics for calls received by a specific phone number handle.

Inbound Phone Number Report Properties

Encoding type:application/json

Schema

Property nameTypeRequiredPIIDescriptionChild properties

handlestring

Optional

PII MTL: 30 days

Inbound phone number handle represented in the report.

totalCallsinteger

Optional

Not PII

Total number of inbound calls observed during the report period.

callAnswerScorenumber<float>

Optional

Not PII

Score (0-100) representing how often inbound calls were answered.

callStatePercentageobject

Optional

Not PII

Percentage of calls by call state (completed, fail, busy, no-answer, canceled).

Show callStatePercentage properties

silentCallsPercentagenumber<float>

Optional

Not PII

Percentage of inbound calls with silence tags over total outbound calls. A silent tag is indicative of a connectivity issue or muted audio.

Create Inbound Phone Numbers Report properties

(information)

Info

A Voice Insights Report will be available for 5 days after it is created.

Property nameTypeRequiredPIIDescriptionChild properties

accountSidSID<AC>

Optional

Not PII

The unique SID identifier of the Account.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

reportIdstring

Optional

Not PII

The report identifier as Voice Insights Report TTID.

statusenum<string>

Optional

Not PII

The status of the report.

Possible values:

createdrunningcompleted

requestMetaobject

Optional

Not PII

Show requestMeta properties

urlstring<uri>

Optional

Not PII

The URL of this resource.

Create Inbound Phone Number Reports

POST https://insights.twilio.com/v2/Voice/Reports/PhoneNumbers/Inbound

Request body parameters

Encoding type:application/json

Schema

Property nameTypeRequiredPIIDescriptionChild properties

timeRangeobject

Optional

Not PII

Show timeRange properties

filtersarray[object]

Optional

Not PII

Show filters properties

sizeinteger

Optional

Not PII

The number of max available top Phone Numbers to generate.

Default: 1000Minimum: 1Maximum: 6000

The recent 7 days report can be created without any parameters.

Create Inbound Phone Number Reports

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createInboundPhoneNumbersReport() {
11  const inbound = await client.insights.v2.inbound().create();
12
13  console.log(inbound.accountSid);
14}
15
16createInboundPhoneNumbersReport();

Response

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "report_id": "voiceinsights_report_01jmzm99cte5rrbbhv8bctd4av",
4  "status": "created",
5  "request_meta": {
6    "start_time": "2024-11-01T00:00:00Z",
7    "end_time": "2024-11-07T00:00:00Z",
8    "filters": []
9  },
10  "url": "https://insights.twilio.com/v2/Voice/Reports/PhoneNumbers/Inbound/voiceinsights_report_01jmzm99cte5rrbbhv8bctd4av"
11}

Generate inbound reports for a specific period by providing the time_range parameter.

Create Inbound Phone Number Reports with Date Time Range

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createInboundPhoneNumbersReport() {
11  const inbound = await client.insights.v2.inbound().create({
12    time_range: {
13      start_datetime: "2024-10-15T00:00:00Z",
14      end_datetime: "2024-11-07T00:00:00Z",
15    },
16  });
17
18  console.log(inbound.accountSid);
19}
20
21createInboundPhoneNumbersReport();

Response

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "report_id": "voiceinsights_report_01jmzm99cte5rrbbhv8bctd4av",
4  "status": "created",
5  "request_meta": {
6    "start_time": "2024-11-01T00:00:00Z",
7    "end_time": "2024-11-07T00:00:00Z",
8    "filters": []
9  },
10  "url": "https://insights.twilio.com/v2/Voice/Reports/PhoneNumbers/Inbound/voiceinsights_report_01jmzm99cte5rrbbhv8bctd4av"
11}

Generate a specific number of outbound reports by providing the size parameter.

Create Inbound Phone Number Reports with Specific Size

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createInboundPhoneNumbersReport() {
11  const inbound = await client.insights.v2.inbound().create({
12    time_range: {
13      start_datetime: "2024-10-15T00:00:00Z",
14      end_datetime: "2024-11-07T00:00:00Z",
15    },
16    size: 100,
17  });
18
19  console.log(inbound.accountSid);
20}
21
22createInboundPhoneNumbersReport();

Response

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "report_id": "voiceinsights_report_01jmzm99cte5rrbbhv8bctd4av",
4  "status": "created",
5  "request_meta": {
6    "start_time": "2024-11-01T00:00:00Z",
7    "end_time": "2024-11-07T00:00:00Z",
8    "filters": []
9  },
10  "url": "https://insights.twilio.com/v2/Voice/Reports/PhoneNumbers/Inbound/voiceinsights_report_01jmzm99cte5rrbbhv8bctd4av"
11}

Fetch Inbound Phone Number Reports

GET https://insights.twilio.com/v2/Voice/Reports/PhoneNumbers/Inbound/{reportId}

Path parameters

Property nameTypeRequiredPIIDescription

reportIdstring

required

Not PII

A unique Report Id.

Query parameters

Property nameTypeRequiredPIIDescription

pageSizeinteger<int64>

Optional

Not PII

How many resources to return in each list page.

Minimum: 1Maximum: 1000

pageinteger

Optional

Not PII

The page index. This value is simply for client state.

Minimum: 0

pageTokenstring

Optional

Not PII

The page token. This is provided by the API.

Fetch Inbound Phone Number Reports

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listInboundPhoneNumbersReport() {
11  const inbounds = await client.insights.v2
12    .inbound("voiceinsights_report_01jmzm99cte5rrbbhv8bctd4av")
13    .list({ limit: 20 });
14
15  inbounds.forEach((i) => console.log(i.handle));
16}
17
18listInboundPhoneNumbersReport();

Response

1{
2  "meta": {
3    "page": 0,
4    "page_size": 50,
5    "first_page_url": "https://insights.twilio.com/v2/Voice/Reports/PhoneNumbers/Inbound/voiceinsights_report_01jmzm99cte5rrbbhv8bctd4av?PageSize=50&Page=0",
6    "previous_page_url": null,
7    "url": "https://insights.twilio.com/v2/Voice/Reports/PhoneNumbers/Inbound/voiceinsights_report_01jmzm99cte5rrbbhv8bctd4av?PageSize=50&Page=0",
8    "next_page_url": null,
9    "key": "reports"
10  },
11  "reports": []
12}