Skip to main content
Contacts are automatically created when you send messages. You can retrieve and update contact information.

​
Get Contact

const result = await client.contacts.get({
  contactId: "con_abc123",
});

console.log(result.id);
console.log(result.phoneNumber);
console.log(result.countryCode);
console.log(result.availableChannels);
console.log(result.defaultChannel);

​
Get Contact by Phone

const result = await client.contacts.getByPhone({
  phoneNumber: "+14155551234",
});

console.log(result.id);
console.log(result.availableChannels); // ["sms", "whatsapp"]

​
Update Contact

const result = await client.contacts.update({
  contactId: "con_abc123",
  defaultChannel: "whatsapp",
  metadata: {
    name: "John Doe",
    tier: "premium",
  },
});

​
List Contacts

const result = await client.contacts.list({
  limit: 50,
});

for (const contact of result.items) {
  console.log(contact.id, contact.phoneNumber);
}

// Filter by phone number
const result = await client.contacts.list({
  phoneNumber: "+1415",
});

// Pagination
let cursor: string | undefined;
do {
  const result = await client.contacts.list({ cursor, limit: 50 });
  for (const contact of result.items) {
    console.log(contact.id);
  }
  cursor = result.nextCursor ?? undefined;
} while (cursor);

​
Phone Introspection

Validate a phone number and check available channels: 
const result = await client.introspect.phone({
  phoneNumber: "+14155551234",
});

console.log(result.validNumber); // true
console.log(result.countryCode); // "US"
console.log(result.nationalFormat); // "(415) 555-1234"
console.log(result.lineType); // "mobile"
console.log(result.availableChannels); // ["sms", "whatsapp"]
console.log(result.carrier?.name); // "Verizon Wireless"