Skip to contentSkip to navigationSkip to topbar
Twilio Docs
Page tools
On this page
Looking for more inspiration?Visit the

Inbound Phone Number Report Resource

On this reference page, you'll learn the properties, parameters, and schemas for the Inbound Phone Number Report resource. See Related how-to documentation to learn the steps to use the info on this page.

Overview

overview page anchor
(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

inbound-phone-number-report-properties page anchor
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).

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

create-inbound-phone-numbers-report-properties page anchor
(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
urlstring<uri>

Optional

Not PII

The URL of this resource.

Create Inbound Phone Number Reports

create-inbound-phone-number-reports page anchor

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

Request body parameters

request-body-parameters page anchor
Encoding type:application/json
Schema
Property nameTypeRequiredPIIDescriptionChild properties
timeRangeobject

Optional

Not PII
filtersarray[object]

Optional

Not PII
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 ReportsLink to code sample: Create Inbound Phone Number Reports
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const 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

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function createInboundPhoneNumbersReport() {

11
  const inbound = await client.insights.v2.inbound().create();

12


13
  console.log(inbound.accountSid);

14
}

15


16
createInboundPhoneNumbersReport();

Response

Note about this response
1
{

2
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "report_id": "voiceinsights_report_01jmzm99cte5rrbbhv8bctd4av",

4
  "status": "created",

5
  "request_meta": {

6
    "start_datetime": "2024-11-01T00:00:00Z",

7
    "end_datetime": "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 RangeLink to code sample: Create Inbound Phone Number Reports with Date Time Range
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const 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

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async 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


21
createInboundPhoneNumbersReport();

Response

Note about this response
1
{

2
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "report_id": "voiceinsights_report_01jmzm99cte5rrbbhv8bctd4av",

4
  "status": "created",

5
  "request_meta": {

6
    "start_datetime": "2024-11-01T00:00:00Z",

7
    "end_datetime": "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 SizeLink to code sample: Create Inbound Phone Number Reports with Specific Size
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const 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

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async 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


22
createInboundPhoneNumbersReport();

Response

Note about this response
1
{

2
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "report_id": "voiceinsights_report_01jmzm99cte5rrbbhv8bctd4av",

4
  "status": "created",

5
  "request_meta": {

6
    "start_datetime": "2024-11-01T00:00:00Z",

7
    "end_datetime": "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

fetch-inbound-phone-number-reports page anchor

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

Path parameters

path-parameters page anchor
Property nameTypeRequiredPIIDescription
reportIdstring
required
Not PII

A unique Report Id.

Query parameters

query-parameters page anchor
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 ReportsLink to code sample: Fetch Inbound Phone Number Reports
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const 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

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async 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


18
listInboundPhoneNumbersReport();

Response

Note about this 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
}