Pricing Updates ✨ Grouped chats and quick actions Login Start your trial

Contacts API

The Contacts API is a powerful tool for managing and interacting with your contacts on the Chatness platform.

Here you will learn how to manage all your contacts within the Chatness Platform. This section provides detailed information about the Contacts API, which covers all attributes of a contact and complete operations on how to list, search, create, and update contacts in a bot.

Org authorization

You'll need to authenticate your requests as an organization to access any of the endpoints in the Contacts API.

Never expose your organization secret to the public.

Contacts attributes

Name
id
Type
string
Description

Unique identifier for the contact

Name
name
Type
string
Description

The name for the contact

Name
email
Type
string
Description

The email for the contact

Name
phone
Type
string
Description

The phone number for the contact

Name
mid
Type
string
Description

The Messenger ID for the contact

Name
wid
Type
string
Description

The WhatsApp ID for the contact

Name
createdAt
Type
string
Description

Timestamp of when the contact was created

Name
updatedAt
Type
string
Description

Timestamp of when the contact was updated on the platform


Create a contact

PUT

/v1/bots/{botId}/contacts

This endpoint allows to create a single contact. If successful, the response will contain the newly created contact ID. Contacts in Chatness are unique by email, so if you try to create a contact with an email that already exists, a 400 error will be returned.

Required attributes

Name
botId
Type
string in pathname
Description

The ID of the bot.

Name
name
Type
string in body
Description

The name for the contact.

Name
email
Type
string in body
Description

The contact email.


Optional attributes

Name
phone
Type
string in body
Description

The phone number for the contact.

Name
wid
Type
string in body
Description

The contact WhatsApp ID. It should be the contact's phone number in the international format with the prefix +

example
+15555550123
Name
mid
Type
string in body
Description

The contact email Messenger ID. It should be the one delivered in Facebook's integration.

Examples
import { Chatness } from '@chatness/server'

const chat = new Chatness({ orgToken, botId })

const contacts = await chat.contacts.create({
  name: 'Jane Doe',
  email: '[email protected]',
  phone: '+18007593001',
  wip: '+15006484001',
})

Generated contact
{
  "data": {
    "id": "j0j0mQxQjl",
    "name": "Jane Doe",
    "email": "[email protected]",
    "phone": "+18007593001",
    "wip": "+15006484001",
    "createdAt": "2023-12-08T00:00:00.000Z",
    "updatedAt": "2023-12-08T00:00:00.000Z"
  }          
}

Upsert contacts

PATCH

/v1/bots/{botId}/contacts

This endpoint allows to create or update many contacts at once. If a contact already exists, it will be updated, otherwise it will be created and its ID returned in the response.

A maximum of 1000 contacts can be upserted in a single request.

Required attributes

Name
botId
Type
string in pathname
Description

The ID of the bot.

Name
data
Type
array in body
Description

The contacts to be updated or inserted


Examples
import { Chatness } from '@chatness/server'

const chat = new Chatness({ orgToken, botId })

const contacts = await chat.contacts.upsert([
  {
    "name": "John Doe",
    "email": "[email protected]",
    "phone": "+18007593000",
    "wid": "+15006484000"
  },
  {
    "name": "Jane Doe",
    "email": "[email protected]",
    "phone": "+18007593001",
    "wid": "+15006484001"
  },
  {
    "name": "Nobody Doe",
    "email": "[email protected]",
    "phone": "+18007593002",
    "wid": "+15006484002"
  }
])

Updated and inserted contacts
{   
  "data": [{
      "index": 1,
      "id": "o4agCI8Ftz"
    },
    {
      "index": 2,
      "id": "iSZiGYxleH"
    }]
}

Search for contacts

POST

/v1/bots/{botId}/contacts

This endpoint allows to retrieve or search a paginated list of all your contacts in your bot. By default, a maximum of 10 contacts are shown per page.

Required attributes

Name
botId
Type
string in pathname
Description

The ID of the bot.


Optional attributes

Name
query
Type
string in queryParams
Description

The search query. It can include any of the contact attributes, except timestamps.

Name
page
Type
number in queryParams
Description

The page number to return.

default
1
Name
limit
Type
number in queryParams
Description

The number of contacts to return per page.

min
1
max
100
default
10
Examples
import { Chatness } from '@chatness/server'

const chat = new Chatness({ orgToken, botId })

const contacts = await chat.contacts.search({
  page: 1,
  limit: 10,
  query: 'john'
})

Contacts response
{        
  "data": [
    {
      "id": "j0j0mQxQjl",
      "name": "John Doe",
      "email": "[email protected]",
      "phone": "+18007593000",
      "mid": "123456789",
      "wid": "+15006484000",
      "createdAt": "2023-12-08T00:00:00.000Z",
      "updatedAt": "2023-12-08T00:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "limit": 10,
    "totalPages": 1,
    "startPage": 1,
    "endPage": 1,
    "startIndex": 0,
    "endIndex": 0,
    "pages": [1]
  }
}

Retrieve a contact

GET

/v1/bots/{botId}/contacts/{contactId}

This endpoint allows to get a contact by its ID.

Required attributes

Name
botId
Type
string in pathname
Description

The ID of the bot.

Name
contactId
Type
string in pathname
Description

The ID of the contact.


Examples
import { Chatness } from '@chatness/server'

const chat = new Chatness({ orgToken, botId })

const contact = await chat
                      .contacts
                      .retrieve('j0j0mQxQjl')

Contact response
{
  "data": {
    "id": "j0j0mQxQjl",
    "name": "John Doe",
    "email": "[email protected]",
    "phone": "+18007593000",
    "mid": "123456789",
    "wid": "+15006484000",
    "createdAt": "2023-12-08T00:00:00.000Z",
    "updatedAt": "2023-12-08T00:00:00.000Z"
  }
}

Update a contact

PATCH

/v1/bots/{botId}/contacts/{contactId}

This endpoint allows to update a contact by its ID. If successful, the response will always be a 200 status. Contacts in Chatness are unique by email, so if you try to update a contact with an email that already exists, a 400 error will be returned.

Required attributes

Name
botId
Type
string in pathname
Description

The ID of the bot.

Name
contactId
Type
string in pathname
Description

The ID of the contact.


Optional attributes

Name
name
Type
string in body
Description

The name for the contact.

Name
email
Type
string in body
Description

The contact email.

Name
phone
Type
string in body
Description

The phone number for the contact.

Name
wid
Type
string in body
Description

The contact WhatsApp ID. It should be the contact's phone number in the international format with the prefix +

Name
mid
Type
string in body
Description

The contact email Messenger ID. It should be the one delivered in Facebook's integration.

Examples
import { Chatness } from '@chatness/server'

const chat = new Chatness({ orgToken, botId })

await chat.contacts.update('j0j0mQxQjl', {
  "name": "Jane X",
  "email": "[email protected]",
  "phone": "+18007593001",
  "wid": "+15006484001"         
})

Delete a contact

DELETE

/v1/bots/{botId}/contacts/{contactId}

This endpoint allows to delete a contact by its ID. If successful, the response will always be a 204 status.

Required attributes

Name
botId
Type
string in pathname
Description

The ID of the bot.

Name
contactId
Type
string in pathname
Description

The ID of the contact.


Examples
import { Chatness } from '@chatness/server'

const chat = new Chatness({ orgToken, botId })

await chat.contacts.delete('j0j0mQxQjl')

Get started with Chatness this afternoon

Each subscription goes towards aggressively adding new features built with customers' best interests at heart, including your privacy.

© 2024 Chatness - A product by IntenseloopChatness uptime in the last 180 days