Skip to content Skip to navigation Skip to topbar

Address Configuration Resource

The Address Configuration resource manages the configurations related to a unique address within the Conversations (classic) product, allowing you to specify which addresses should auto-create a Conversation upon receiving an inbound message.
The unique address must be a single address (i.e. a WhatsApp or SMS phone number) that belongs to your Twilio Account.

The configuration can optionally include automatically attaching a Conversation-scoped Webhook to the auto-created conversations.

AddressConfiguration properties

Property nameTypeRequiredPIIDescriptionChild properties

sidSID<IG>

Optional

A 34 character string that uniquely identifies this resource.

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

accountSidSID<AC>

Optional

The unique ID of the Account the address belongs to

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

typestring

Optional

Type of Address, value can be whatsapp or sms.

addressstring

Optional

PII MTL: 30 days

The unique address to be configured. The address can be a whatsapp address or phone number

friendlyNamestring

Optional

The human-readable name of this configuration, limited to 256 characters. Optional.

autoCreation

Optional

Auto Creation configuration for the address.

dateCreatedstring<date-time>

Optional

The date that this resource was created.

dateUpdatedstring<date-time>

Optional

The date that this resource was last updated.

urlstring<uri>

Optional

An absolute API resource URL for this address configuration.

addressCountrystring

Optional

An ISO 3166-1 alpha-2n country code which the address belongs to. This is currently only applicable to short code addresses.

Create an AddressConfiguration resource

POST https://conversations.twilio.com/v1/Configuration/Addresses

Request body parameters

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

typeenum<string>

required

Type of Address, value can be whatsapp or sms.

Possible values:

smswhatsappmessengergbmemailrcsapplechat

addressstring

required

PII MTL: 30 days

The unique address to be configured. The address can be a whatsapp address or phone number

friendlyNamestring

Optional

The human-readable name of this configuration, limited to 256 characters. Optional.

autoCreation.enabledboolean

Optional

Enable/Disable auto-creating conversations for messages to this address

autoCreation.typeenum<string>

Optional

Possible values:

webhookstudiodefault

autoCreation.conversationServiceSidSID<IS>

Optional

Conversation Service for the auto-created conversation. If not set, the conversation is created in the default service.

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

autoCreation.webhookUrlstring

Optional

For type webhook, the url for the webhook request.

autoCreation.webhookMethodenum<string>

Optional

Possible values:

getpost

autoCreation.webhookFiltersarray[string]

Optional

The list of events, firing webhook event for this Conversation. Values can be any of the following: onMessageAdded, onMessageUpdated, onMessageRemoved, onConversationUpdated, onConversationStateUpdated, onConversationRemoved, onParticipantAdded, onParticipantUpdated, onParticipantRemoved, onDeliveryUpdated

autoCreation.studioFlowSidSID<FW>

Optional

For type studio, the studio flow SID where the webhook should be sent to.

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

autoCreation.studioRetryCountinteger

Optional

For type studio, number of times to retry the webhook request

addressCountrystring

Optional

An ISO 3166-1 alpha-2n country code which the address belongs to. This is currently only applicable to short code addresses.

Create Address Configuration

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 at twilio.com/console
5// Provision API Keys at twilio.com/console/runtime/api-keys
6// and set the environment variables. See http://twil.io/secure
7// For local testing, you can use your Account SID and Auth token
8const accountSid = process.env.TWILIO_ACCOUNT_SID;
9const apiKey = process.env.TWILIO_API_KEY;
10const apiSecret = process.env.TWILIO_API_SECRET;
11const client = twilio(apiKey, apiSecret, { accountSid: accountSid });
12
13async function createConfigurationAddress() {
14  const addressConfiguration =
15    await client.conversations.v1.addressConfigurations.create({
16      address: "+37256123457",
17      "autoCreation.conversationServiceSid": "ISXXXXXXXXXXXXXXXXXXXXXX",
18      "autoCreation.enabled": true,
19      "autoCreation.type": "webhook",
20      "autoCreation.webhookFilters": ["onParticipantAdded", "onMessageAdded"],
21      "autoCreation.webhookMethod": "get",
22      "autoCreation.webhookUrl": "https://example.com",
23      friendlyName: "My Test Configuration",
24      type: "sms",
25    });
26
27  console.log(addressConfiguration.sid);
28}
29
30createConfigurationAddress();

Response

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "sid": "IGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "address": "+37256123457",
5  "type": "sms",
6  "friendly_name": "My Test Configuration",
7  "address_country": "CA",
8  "auto_creation": {
9    "enabled": true,
10    "type": "webhook",
11    "conversation_service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
12    "webhook_url": "https://example.com",
13    "webhook_method": "POST",
14    "webhook_filters": [
15      "onParticipantAdded",
16      "onMessageAdded"
17    ]
18  },
19  "date_created": "2016-03-24T21:05:50Z",
20  "date_updated": "2016-03-24T21:05:50Z",
21  "url": "https://conversations.twilio.com/v1/Configuration/Addresses/IGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
22}

Fetch an AddressConfiguration resource

GET https://conversations.twilio.com/v1/Configuration/Addresses/{Sid}

Path parameters

Property nameTypeRequiredPIIDescription

sidstring

required

The SID of the Address Configuration resource. This value can be either the sid or the address of the configuration

Fetch Address Configuration

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 at twilio.com/console
5// Provision API Keys at twilio.com/console/runtime/api-keys
6// and set the environment variables. See http://twil.io/secure
7// For local testing, you can use your Account SID and Auth token
8const accountSid = process.env.TWILIO_ACCOUNT_SID;
9const apiKey = process.env.TWILIO_API_KEY;
10const apiSecret = process.env.TWILIO_API_SECRET;
11const client = twilio(apiKey, apiSecret, { accountSid: accountSid });
12
13async function fetchConfigurationAddress() {
14  const addressConfiguration = await client.conversations.v1
15    .addressConfigurations("IGXXXXXXXXXXXXXXXXXXXXXXXX")
16    .fetch();
17
18  console.log(addressConfiguration.sid);
19}
20
21fetchConfigurationAddress();

Response

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "sid": "IGXXXXXXXXXXXXXXXXXXXXXXXX",
4  "address": "+37256123457",
5  "type": "sms",
6  "friendly_name": "My Test Configuration",
7  "address_country": "CA",
8  "auto_creation": {
9    "enabled": true,
10    "type": "webhook",
11    "conversation_service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
12    "webhook_url": "https://example.com",
13    "webhook_method": "POST",
14    "webhook_filters": [
15      "onParticipantAdded",
16      "onMessageAdded"
17    ]
18  },
19  "date_created": "2016-03-24T21:05:50Z",
20  "date_updated": "2016-03-24T21:05:50Z",
21  "url": "https://conversations.twilio.com/v1/Configuration/Addresses/IGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
22}

Read multiple AddressConfiguration resources

GET https://conversations.twilio.com/v1/Configuration/Addresses

Query parameters

Property nameTypeRequiredPIIDescription

typestring

Optional

Filter the address configurations by its type. This value can be one of: whatsapp, sms.

pageSizeinteger<int64>

Optional

How many resources to return in each list page. The default is 50, and the maximum is 50.

Minimum: 1Maximum: 50

pageinteger

Optional

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

Minimum: 0

pageTokenstring

Optional

The page token. This is provided by the API.

List Address Configurations

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 at twilio.com/console
5// Provision API Keys at twilio.com/console/runtime/api-keys
6// and set the environment variables. See http://twil.io/secure
7// For local testing, you can use your Account SID and Auth token
8const accountSid = process.env.TWILIO_ACCOUNT_SID;
9const apiKey = process.env.TWILIO_API_KEY;
10const apiSecret = process.env.TWILIO_API_SECRET;
11const client = twilio(apiKey, apiSecret, { accountSid: accountSid });
12
13async function listConfigurationAddress() {
14  const addressConfigurations =
15    await client.conversations.v1.addressConfigurations.list({ limit: 20 });
16
17  addressConfigurations.forEach((a) => console.log(a.sid));
18}
19
20listConfigurationAddress();

Response

1{
2  "meta": {
3    "page": 0,
4    "page_size": 50,
5    "first_page_url": "https://conversations.twilio.com/v1/Configuration/Addresses?PageSize=50&Page=0",
6    "previous_page_url": null,
7    "url": "https://conversations.twilio.com/v1/Configuration/Addresses?PageSize=50&Page=0",
8    "next_page_url": null,
9    "key": "address_configurations"
10  },
11  "address_configurations": [
12    {
13      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
14      "sid": "IGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
15      "address": "+37256123457",
16      "type": "sms",
17      "friendly_name": "My Test Configuration",
18      "address_country": "CA",
19      "auto_creation": {
20        "enabled": true,
21        "type": "webhook",
22        "conversation_service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
23        "webhook_url": "https://example.com",
24        "webhook_method": "POST",
25        "webhook_filters": [
26          "onParticipantAdded",
27          "onMessageAdded"
28        ]
29      },
30      "date_created": "2016-03-24T21:05:50Z",
31      "date_updated": "2016-03-24T21:05:50Z",
32      "url": "https://conversations.twilio.com/v1/Configuration/Addresses/IGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
33    },
34    {
35      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
36      "sid": "IGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaab",
37      "address": "+37256123458",
38      "type": "sms",
39      "friendly_name": "Studio Test Configuration",
40      "address_country": "US",
41      "auto_creation": {
42        "enabled": false,
43        "type": "studio",
44        "conversation_service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
45        "studio_flow_sid": "FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
46        "studio_retry_count": 3
47      },
48      "date_created": "2016-03-24T21:05:50Z",
49      "date_updated": "2016-03-24T21:05:50Z",
50      "url": "https://conversations.twilio.com/v1/Configuration/Addresses/IGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaab"
51    },
52    {
53      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
54      "sid": "IGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaac",
55      "address": "+37256123459",
56      "type": "sms",
57      "friendly_name": "Default Test Configuration",
58      "address_country": "NG",
59      "auto_creation": {
60        "enabled": true,
61        "type": "default"
62      },
63      "date_created": "2016-03-24T21:05:50Z",
64      "date_updated": "2016-03-24T21:05:50Z",
65      "url": "https://conversations.twilio.com/v1/Configuration/Addresses/IGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaac"
66    }
67  ]
68}

Update an AddressConfiguration resource

POST https://conversations.twilio.com/v1/Configuration/Addresses/{Sid}

Path parameters

Property nameTypeRequiredPIIDescription

sidstring

required

The SID of the Address Configuration resource. This value can be either the sid or the address of the configuration

Request body parameters

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

friendlyNamestring

Optional

The human-readable name of this configuration, limited to 256 characters. Optional.

autoCreation.enabledboolean

Optional

Enable/Disable auto-creating conversations for messages to this address

autoCreation.typeenum<string>

Optional

Possible values:

webhookstudiodefault

autoCreation.conversationServiceSidSID<IS>

Optional

Conversation Service for the auto-created conversation. If not set, the conversation is created in the default service.

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

autoCreation.webhookUrlstring

Optional

For type webhook, the url for the webhook request.

autoCreation.webhookMethodenum<string>

Optional

Possible values:

getpost

autoCreation.webhookFiltersarray[string]

Optional

The list of events, firing webhook event for this Conversation. Values can be any of the following: onMessageAdded, onMessageUpdated, onMessageRemoved, onConversationUpdated, onConversationStateUpdated, onConversationRemoved, onParticipantAdded, onParticipantUpdated, onParticipantRemoved, onDeliveryUpdated

autoCreation.studioFlowSidSID<FW>

Optional

For type studio, the studio flow SID where the webhook should be sent to.

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

autoCreation.studioRetryCountinteger

Optional

For type studio, number of times to retry the webhook request

Update Address Configuration

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 at twilio.com/console
5// Provision API Keys at twilio.com/console/runtime/api-keys
6// and set the environment variables. See http://twil.io/secure
7// For local testing, you can use your Account SID and Auth token
8const accountSid = process.env.TWILIO_ACCOUNT_SID;
9const apiKey = process.env.TWILIO_API_KEY;
10const apiSecret = process.env.TWILIO_API_SECRET;
11const client = twilio(apiKey, apiSecret, { accountSid: accountSid });
12
13async function updateConfigurationAddress() {
14  const addressConfiguration = await client.conversations.v1
15    .addressConfigurations("IGXXXXXXXXXXXXXXXXXXXXXXX")
16    .update({
17      "autoCreation.enabled": false,
18      "autoCreation.studioFlowSid": "FWXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
19      "autoCreation.studioRetryCount": 3,
20      "autoCreation.type": "studio",
21      friendlyName: "My Test Configuration Updated",
22    });
23
24  console.log(addressConfiguration.sid);
25}
26
27updateConfigurationAddress();

Response

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "sid": "IGXXXXXXXXXXXXXXXXXXXXXXX",
4  "address": "+37256123457",
5  "type": "sms",
6  "friendly_name": "My Test Configuration Updated",
7  "address_country": "CA",
8  "auto_creation": {
9    "enabled": false,
10    "type": "studio",
11    "conversation_service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
12    "studio_flow_sid": "FWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
13    "studio_retry_count": 3
14  },
15  "date_created": "2016-03-24T21:05:50Z",
16  "date_updated": "2016-03-24T21:05:51Z",
17  "url": "https://conversations.twilio.com/v1/Configuration/Addresses/IGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
18}

Delete an AddressConfiguration resource

DELETE https://conversations.twilio.com/v1/Configuration/Addresses/{Sid}

Path parameters

Property nameTypeRequiredPIIDescription

sidstring

required

The SID of the Address Configuration resource. This value can be either the sid or the address of the configuration

Delete Address Configuration

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 at twilio.com/console
5// Provision API Keys at twilio.com/console/runtime/api-keys
6// and set the environment variables. See http://twil.io/secure
7// For local testing, you can use your Account SID and Auth token
8const accountSid = process.env.TWILIO_ACCOUNT_SID;
9const apiKey = process.env.TWILIO_API_KEY;
10const apiSecret = process.env.TWILIO_API_SECRET;
11const client = twilio(apiKey, apiSecret, { accountSid: accountSid });
12
13async function deleteConfigurationAddress() {
14  await client.conversations.v1
15    .addressConfigurations("IGXXXXXXXXXXXXXXXXXXX")
16    .remove();
17}
18
19deleteConfigurationAddress();