Skip to content

Create or update a contact ​

POST /v2/contact/createOrUpdate

For the base URL, request headers and response codes, see the overview.

The contact is matched by Telephone: if no contact has that number, one is created; otherwise the existing contact is updated.

Request body ​

FieldTypeRequiredDescription
ChannelTypeStringYesChannel type. Only "whatsapp" is accepted
TelephoneStringYesThe contact's phone number including country code, for example +85261234567
FirstNameStringNoFirst name. When creating a contact without it, LastName is used instead; if both are missing, the phone number is used
LastNameStringNoLast name
EmailStringNoEmail address
TagsObjectNoAdd or remove tags; see below
ListsObjectNoAdd to or remove from lists; see below
SubscribedChannelsArray<String>NoIDs of the WhatsApp channels the contact subscribes to
CustomFieldsArray<Object>NoCustom field values; see below

Tags / Lists object

FieldTypeDescription
OperateString"add" to add, or "del" to remove
ValuesArray<String>Tag or list names

CustomFields item

FieldTypeDescription
FieldNameStringCustom field name
ValueStringField value

Create tags, lists and custom fields first

Names are matched against what already exists in your workspace. The API does not create tags, lists or custom fields. An unknown name is skipped and reported in Message, and the rest of the request is still saved.

Example request ​

bash
curl -X POST "https://api.chatbooster.ai/v2/contact/createOrUpdate" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ChannelType": "whatsapp",
    "FirstName": "Peter",
    "LastName": "Chan",
    "Telephone": "+85261234567",
    "Email": "[email protected]",
    "Tags": { "Operate": "add", "Values": ["VIP", "Newsletter"] },
    "Lists": { "Operate": "add", "Values": ["Members"] },
    "CustomFields": [
      { "FieldName": "Company", "Value": "Example Ltd" }
    ]
  }'

Response ​

FieldTypeDescription
CodeInteger200 on success
MessageString"success" when everything was applied; otherwise lists what was skipped, for example "tag[VIP] not exist;"
json
{
  "Code": 200,
  "Message": "success"
}

Check Message as well

Even when Code is 200, Message may report tags, lists, channels or custom fields that could not be applied.