> For the complete documentation index, see [llms.txt](https://help.clickatell.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.clickatell.com/chat-flow/configuration/clickatell-contact-book.md).

# Clickatell Contact Book

The Clickatell Contact Book provides a link between the ways a customer can be identified on a messaging channel:

* Channel user ID: The identifier a channel (such as WhatsApp) gives a person.&#x20;
* Username: This visible when a user hides their phone number (MSISDN) and only presents their username.&#x20;
* Phone number.&#x20;

The Contact Book can thus answer two simple questions:

* We have this person's channel user ID, what is the phone number?
* We have this person's phone number, what is the channel user ID?

{% hint style="info" %}
All entries are scoped to your account, so your contacts are only ever matched within your own data.
{% endhint %}

As channels like WhatsApp move toward username-based identities, the phone number is not always sent with an incoming message. The Contact Book bridges that gap so that your messaging experience can:&#x20;

* Recognise a returning customer across conversations.&#x20;
* Continue communicating with a customer on another channel (for example, following up by SMS) using the correct number.&#x20;
* Keep one consistent view of a customer even when a channel only provides a handle.&#x20;

In short: it gives you a stable, consistent customer identity even when a channel hides or changes the underlying details.&#x20;

#### How is the Contact Book enabled?

Before identity resolution is available on your account:&#x20;

1. Legal Confirmation: Ensure that you have signed the legal agreement with Clickatell.
2. Confirm the Contact Book is enabled on your account. If it is not, ask your Clickatell account team to enable it.&#x20;
3. Make sure the channel(s) you use are set up (for example, WhatsApp) and connected to your Clickatell messaging.&#x20;
4. Agree your phone-number format with your Clickatell account team.

Your Clickatell account team handles the setup — there is nothing to install or configure on your side.&#x20;

#### How to ensure the best results:

| **What you provide / confirm**                                                  | **Why it matters**                                                          |
| ------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| The channels you use (e.g. WhatsApp, SMS) are correctly set up with Clickatell. | Resolution is per channel, so each channel must be connected.               |
| A consistent phone-number format across your systems.                           | Numbers must be stored and searched the same way, or a match can be missed. |
| Accurate customer details where you supply them (e.g. from your CRM).           | The link is only as good as the information behind it.                      |
|                                                                                 |                                                                             |

**About phone number format:** your systems and Clickatell should use the same number format so that resolution works reliably. If you are unsure which format applies to your setup, confirm it with your Clickatell account team before going live — this avoids matches being missed simply because a number was stored differently from how it is searched.

#### What else you need to know:

You do not operate the Contact Book directly. It works automatically as part of your Clickatell messaging setup. Once it is enabled on your account, identity resolution happens behind the scenes:&#x20;

* When a message comes in, the service can resolve the channel user ID to the customer’s phone number (and the reverse), so the rest of your messaging journey has the right details to work with.&#x20;
* As customers interact, their link between channel user ID and phone number is kept up to date automatically.&#x20;
* Everything is kept within your account — there is no cross-account matching.&#x20;

Because this runs automatically, there are no tokens to manage, no credentials to hold, and no special network access for your team to arrange.&#x20;

#### Troubleshooting

| **What you notice**                                            | **Likely cause**                                                                             | **What to do**                                                                                             |
| -------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| A known customer is not being recognized across conversations. | No link exists yet for that channel and customer, or it was recorded on a different channel. | Raise it with your Clickatell account team with the channel and an example.                                |
| A customer’s details appear out of date.                       | The link was created earlier and has not refreshed.                                          | Your account team can check and refresh the record.                                                        |
| Resolution seems to miss a phone number you expect.            | The number is stored in a different format than it is searched with.                         | Confirm your agreed phone-number format with your account team and keep it consistent across your systems. |
| The Contact Book does not seem to be active.                   | The feature may not be enabled on your account.                                              | Ask your Clickatell account team to confirm it is enabled.                                                 |

If a customer asks to access or delete the personal data held about them (for example, under POPIA or GDPR), these actions are handled by Clickatell on your behalf.&#x20;

**What to do:** raise a request with your Clickatell account team and include:&#x20;

* Your account name,&#x20;
* The channel(s) involved, and&#x20;
* The specific request (for example, “export all contact data for this account” or “delete this customer’s contact”).&#x20;
