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.

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',
})

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

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

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

import { Chatness } from '@chatness/server'

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

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

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

import { Chatness } from '@chatness/server'

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

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

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

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.

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.