Contacts

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.

Authentication

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

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

PUT/v1/bots/{botId}/contacts

Create a contact

This endpoint allows you 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
Description
The ID of the bot.
- in pathname
Name
name
Type
string
Description
The name for the contact.
- in body
Name
email
Type
string
Description
The contact email.
- in body

Optional attributes

Name
phone
Type
string
Description
The phone number for the contact.
- in body
Name
wid
Type
string
Description
The contact WhatsApp ID. It should be the contact's phone number in the international format with the prefix +
- in body
- e.g. +15555550123
Name
mid
Type
string
Description
The contact email Messenger ID. It should be the one delivered in Facebook's integration.
- in body

Request

PUT

/v1/bots/{botId}/contacts

curl -X PUT '/v1/bots/{botId}/contacts' \
  -H "Authorization: {orgToken}" \
  -d name="Jane Doe" \
  -d email="[email protected]"

{
  "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"
  }          
}

PATCH/v1/bots/{botId}/contacts

Upsert contacts

This endpoint allows you 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.

maximum: 1000

Required attributes

Name
botId
Type
string
Description
The ID of the bot.
- in pathname
Name
data
Type
array
Description
The contacts to be updated or inserted
- in body

Request

PATCH

/v1/bots/{botId}/contacts

curl -X PATCH '/v1/bots/{botId}/contacts' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {orgToken}' \
  --data-raw '{
    "data": [{
      "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"
    }]
  }'

{   
  "data": [{
      "index": 1,
      "id": "o4agCI8Ftz"
    },
    {
      "index": 2,
      "id": "iSZiGYxleH"
    }]
}

POST/v1/bots/{botId}/contacts

Search for contacts

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

Required attributes

Name
botId
Type
string
Description
The ID of the bot.
- in pathname

Optional attributes

Name
query
Type
string
Description
The search query. It can include any of the contact attributes, except timestamps.
- in queryParams
Name
page
Type
number
Description
The page number to return.
- in queryParams
- default 1
- e.g. 1
Name
limit
Type
number
Description
The number of contacts to return per page.
- in queryParams
- default 10
- minimum 1
- maximum 100
- e.g. 10

Request

POST

/v1/bots/{botId}/contacts

curl -X POST '/v1/bots/{botId}/contacts?query=john&page=1&limit=10' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {orgToken}'

{        
  "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]
  }
}

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

Retrieve a contact

This endpoint allows you to get a contact by its ID.

Required attributes

Name
botId
Type
string
Description
The ID of the bot.
- in pathname
Name
contactId
Type
string
Description
The ID of the contact.
- in pathname

Request

GET

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

curl -X GET '/v1/bots/{botId}/contacts/{contactId}' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {orgToken}'

{
  "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"
  }
}

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

Update a contact

This endpoint allows you to update a contact by its ID. If successful, the response will only contain 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
Description
The ID of the bot.
- in pathname
Name
contactId
Type
string
Description
The ID of the contact.
- in pathname

Optional attributes

Name
name
Type
string
Description
The name for the contact.
- in body
Name
email
Type
string
Description
The contact email.
- in body
Name
phone
Type
string
Description
The phone number for the contact.
- in body
Name
wid
Type
string
Description
The contact WhatsApp ID. It should be the contact's phone number in the international format with the prefix +
- in body
Name
mid
Type
string
Description
The contact email Messenger ID. It should be the one delivered in Facebook's integration.
- in body

Request

PATCH

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

curl -X PATCH '/v1/bots/{botId}/contacts/{contactId}' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {orgToken}' \
  --data-raw '{
    "name": "Jane X",
    "email": "[email protected]",
    "phone": "+18007593001",
    "wid": "+15006484001"
  }'

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

Delete a contact

This endpoint allows you to delete a contact by its ID. If successful, the response will only contain a 204 status.

Required attributes

Name
botId
Type
string
Description
The ID of the bot.
- in pathname
Name
contactId
Type
string
Description
The ID of the contact.
- in pathname

Request

DELETE

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

curl -X DELETE '/v1/bots/{botId}/contacts/{contactId}' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {orgToken}'