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.

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

Typical Flow Pattern

┌─────────────┐     ┌──────────────────┐     ┌─────────────────────┐
│   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)    │
                    └──────────────────┘

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, 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.

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