> For the complete documentation index, see [llms.txt](https://guides.clickatell.com/flow/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guides.clickatell.com/flow/action-nodes/contact-book.md).
# Contact Book
### Overview
The *Contact Book* action node links a customer's channel identity (e.g. their WhatsApp Business-Scoped User ID) to their phone number (MSISDN). This is essential on channels where the platform receives a pseudonymous ID rather than the customer's actual phone number.
### Prerequisites
The Contact Book feature must be enabled for your account before this node becomes available. Contact your Clickatell administrator to opt into the Contact Book feature.
### When to Use
Use this node when your flow needs to:
* Check whether a customer's phone number is already known.
* Collect and store a customer's phone number for future sessions.
### Configuration
| Field | Description |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| **Resume Original Flow** | When enabled on Insert, redirects the customer back to the flow/step they were on before being routed to the Contact Book flow. |
| **Name** | A descriptive label for this node. |
| **MSISDN** | The phone number to store — typically a session variable collected from a preceding input node. Only applicable for Insert. |
| **Description** | What the node does in your flow's context. |
| **Contact Type** | Lookup or Insert (see below) |
### Contact Type: Lookup
Checks whether the current customer already has a phone number stored in the Contact Book.
**Outputs:**
* **Yes** → Contact found. The customer's MSISDN is available in the session for use in subsequent nodes.
* **No** → Contact not found. Route the customer to collect their phone number.
**Example:** Place at the start of your flow to determine if you already know the customer's phone number. If Yes, proceed normally. If No, branch to a phone collection sub-flow.
### Contact Type: Insert
Stores a phone number against the current customer's channel identity.
**Outputs:**
* **Yes** → Successfully saved. If Resume Original Flow is enabled, the customer is redirected back to their original flow.
* **No** → Save failed (e.g. invalid data or service error).
**Example use:** After collecting the customer's phone number via an input node, use Insert to save the mapping. The customer will never be asked again in future sessions.
### How It Works
1. The node identifies the customer using their **channelUserId** (set automatically by the platform from the incoming message).
2. It calls the Contact Book service with the customer's account ID, channel ID, and the customer's channel user ID.
3. **For Lookup:** returns whether a matching record exists. If found, the MSISDN is placed into the session.
4. **For Insert:** creates or updates the mapping between **channelUserId** and the provided MSISDN, then stores the MSISDN in the session.
### Resume Original Flow
When the Contact Book action node is used within a dedicated "collect phone number" flow (triggered automatically by the platform for unknown contacts), enabling **Resume Original Flow** on a successful Insert sends the customer back to the original flow they were trying to reach. The platform automatically saves and restores the return destination.
{% code overflow="wrap" lineNumbers="true" %}
```java
Customer sends message → Platform detects unknown BSUID →
Contact Book system flow triggered → Ask for phone number →
Insert with Resume Original Flow ON → Customer returns to original flow
```
{% endcode %}
### Typical Flow Pattern
{% code overflow="wrap" lineNumbers="true" %}
```
┌─────────────┐ ┌──────────────────┐ ┌─────────────────────┐
│ Start │────>│ Contact Book │────>│ Continue flow │
│ │ │ (Lookup) │ Yes │ (MSISDN available) │
└─────────────┘ └──────────────────┘ └─────────────────────┘
│ No
▼
┌──────────────────┐
│ Ask for phone │
│ number (Input) │
└──────────────────┘
│
▼
┌──────────────────┐ ┌─────────────────────┐
│ Contact Book │────>│ Resume Original Flow │
│ (Insert) │ Yes │ or continue │
└──────────────────┘ └─────────────────────┘
│ No
▼
┌──────────────────┐
│ Error message │
│ (end session) │
└──────────────────┘
```
{% endcode %}
### Availability
| Aspect | Detail |
| --------------------------- | --------------------------------------------------------------------- |
| **Feature opt-in required** | Yes — Contact Book must be enabled on your account. |
| **Channels** | All (primarily relevant for WhatsApp and other BSUID-based channels). |
| **Node category** | Action. |
| **Environments** | Dev, QA, Sandbox, Production (per-client enablement). |
## Flow Preview
When you've opted in to Contact Book, you will be able to[ preview a flow](/flow/workflow-management/using-the-previewer.md), simulating BSUID &/ trigger a Contact Book flow.
When Trigger Contact Book Flow is checked (Simulate BSUID must be checked too), the emulator performs the Contact Book lookup.
* If the BSUID is not found (404), the Contact Book system flow is triggered (phone number collection).
* Use this to test the full end-to-end "unknown user" path.
If Trigger Contact Book Flow is unchecked, the emulator skips the Contact Book lookup entirely. You can use this when you want to test other parts of your flow without the Contact Book interaction.
#### Testing scenarios
| Simulate BSUID | Trigger Contact Book Flow | What happens |
| -------------- | ------------------------- | --------------------------------------------------------------------------------------------------------- |
| ☐ Off | ☐ Off | Normal preview — phone from source field, auto-saved to Contact Book, no lookup. |
| ☑ On | ☐ Off | BSUID in source field, but Contact Book lookup is skipped — for testing flow logic without Contact Book. |
| ☑ On | ☑ On | Full Contact Book test — BSUID lookup runs, if not found, phone number collection flow will be triggered. |
{% hint style="info" %}
"Simulate BSUID" without "Trigger Contact Book Flow" is useful when you want to test how your flow handles BSUID identifiers without actually hitting the Contact Book service.
{% endhint %}