Overview
This integration allows you to send contacts and audience segments from Zeotap CDP directly into Hello Charles, so your conversational commerce and WhatsApp messaging workflows always run on fresh customer data. Once you set up the Hello Charles destination and attach it to an audience, Zeotap automatically upserts contacts in Hello Charles in batches — creating new contacts and updating existing ones based on the external reference ID you map. You can also send tags and custom properties so you can recreate your Zeotap audience segmentation inside Hello Charles for downstream filtering and outreach.The Hello Charles Batched Contacts API is currently in closed beta. You will need approval from your Hello Charles success manager before this integration can be enabled.
How It Works
When you attach the Hello Charles destination to an audience in Zeotap CDP, the following happens automatically behind the scenes:- You set up Hello Charles as a destination in Zeotap CDP by entering your API Key and your customer-specific Base URL.
- You select the Send Contacts to Hello Charles action and configure the field mapping — telling Zeotap which identifier, names, phone numbers, emails, tags, and custom properties to send.
- You attach the destination to an audience in Zeotap.
- Zeotap upserts the contacts in Hello Charles in batches of up to 1,000 — existing contacts are updated and new contacts are created, matched by the external reference ID you map.
- Tags and custom properties land alongside the contact data, letting you filter and segment those contacts inside Hello Charles afterwards.
Before You Begin
Make sure you have everything ready before starting the setup. In Hello Charles:- An active Hello Charles account with API access enabled.
- Approval from a Hello Charles success manager to access the closed-beta Batched Contacts API.
- Your customer-specific Base URL (the subdomain segment of your Hello Charles workspace URL).
- A valid API Key generated from your Hello Charles account.
- Any tags you plan to send already created in Hello Charles (Settings → Manage Tags).
- Any custom properties you plan to send already created in Hello Charles, with their technical names noted.
- Access to the Integrate module with permission to create new destinations.
- An audience segment ready to send to Hello Charles.
- The user identifier you plan to use as the external reference ID (usually a phone number).
- Phone numbers in your audience formatted correctly — see Important Notes below.
Get Your API Key from Hello Charles
Before connecting Zeotap to Hello Charles, generate (or copy) the API Key Zeotap will use to authenticate.
Create a key for Zeotap (if you don't already have one)
Click Create API Key, then:
- Enter a recognisable name (e.g.,
Zeotap CDP Integration) and a short description. - Set the permissions — admin permissions are recommended so the integration can both upsert contacts and write tags / custom properties.
- Click Save.
Pre-create Tags and Custom Properties in Hello Charles
This is a critical preparation step. Tags and custom properties must exist in Hello Charles before you send them from Zeotap — otherwise Hello Charles will not ingest those values.Create the tags
Navigate to Settings → Manage Tags. Create any tags you plan to send from Zeotap. For example, if you want to mark contacts in an audience with ID 
984, create a tag called 984 (or any label that fits your taxonomy).Create the custom properties
Navigate to the Custom Properties area in your Hello Charles workspace. For each custom property you want to send (e.g., loyalty tier, last purchase date, audience name), create the property and note its technical name — this is the exact string you will use as the mapping key in Zeotap.
Create the Hello Charles Destination in Zeotap CDP
Open the Destinations catalogue
Log in to Zeotap CDP and go to Integrate → Destinations. Click + Create Destination, then search for Hello Charles in the catalogue and select the Hello Charles card.
Enter the destination details
Fill in the configuration fields:
- Destination Name — a descriptive label (e.g.,
Hello Charles V1 TestingorHello Charles — VIP Sync). - Base URL — the Base URL for your Hello Charles API endpoint (the subdomain segment of your Hello Charles workspace URL).
- API Key — paste the API Key you copied from Hello Charles. The field is masked once saved.
Choose the action and map the fields
On the Mapping screen:
- Under Choose your Action, select Send Contacts to Hello Charles — this is the only action available for this destination.
-
In the Map the Fields area, map your Zeotap catalogue fields to the Hello Charles destination fields:
Zeotap Catalogue Field Hello Charles Destination Field Required? Notes User ID / Phone Number External Reference Id Required Used to match existing contacts for upsert. Typically a phone number in international format. First Name First Name Optional Last Name Last Name Optional Phone Number PhoneNumber Optional Sent to Hello Charles as the contact’s main phone number by default — it will not populate other phone slots. Required only when creating new contacts; can be omitted when updating existing contacts or adding tags only. Email Email Address Optional Sent to Hello Charles as the contact’s main email address by default. Required only when creating new contacts; can be omitted when updating existing contacts or adding tags only. Tags Tags Optional Each tag must already exist in Hello Charles. Custom Properties Custom Properties Optional Keys must match Hello Charles technical names exactly.
Map Audience or Segment Data for Segmentation
To recreate your Zeotap audience structure inside Hello Charles, use a tag or custom property to carry the audience identifier. Decide how you want to represent audience membership in Hello Charles:- Option A — Tag: Map your Zeotap audience ID (or the Segment Membership (List) catalogue field) to Tags so every contact in this sync gets tagged with that audience ID.
- Option B — Custom Property: Map the Zeotap audience name or ID to a custom property like
zeotap_audience_nameso the value is stored as a structured field on the contact.
Attach the Destination to an Audience
With the destination and mapping saved, link it to your audience.Open the audience flow
Navigate to your Audience flow in Zeotap CDP and select the audience containing the fields you want to send (e.g., email, phone, last name).
Drag in the Hello Charles destination
Drag and drop the Hello Charles destination into the audience flow, then select the mapping you saved in the previous section.
Field Mapping
Below is the complete reference for how data from Zeotap CDP maps to Hello Charles.Contact Fields
| Zeotap Field | Required / Optional | Notes |
|---|---|---|
| External Reference Id | Required | The unique identifier used to upsert contacts — typically a phone number in international format. |
| First Name | Optional | |
| Last Name | Optional | |
| PhoneNumber | Optional | Phone in international format (+CountryCodeNumber). Sent to Hello Charles as the main phone number by default. |
| Email Address | Optional | A valid email address. Sent to Hello Charles as the main email address by default. |
| Tags | Optional | Each tag must already exist in Hello Charles → Settings → Manage Tags. |
| Custom Properties | Optional | Keys must match Hello Charles technical names exactly. Values can be strings, numbers, or dates. |
How Upsert Works
- Contacts are matched on External Reference Id.
- If a matching contact exists in Hello Charles, it is updated with the new field values.
- If no match exists, a new contact is created.
- Sending a tag adds it to the contact’s tag list; sending a custom property sets or overwrites that property.
Activate and Test the Integration
Once the audience is attached and saved, follow these steps to verify the sync.Confirm contacts in Hello Charles
Log in to Hello Charles and navigate to the Contacts area. Search for one of the contacts from your Zeotap audience (e.g., by phone number or External Reference Id) and confirm:
- The contact appears with the name, phone, and email you mapped.
- The tags you sent are attached to the contact.
- The custom properties you sent appear with the correct values.
Verify the audience as a Hello Charles segment
Navigate to Segments & Lists in Hello Charles and create a new segment. Filter by the tag or custom property you used to mark this audience — for example, 
Contact's custom property → Zeotap Audience Name contains <your audience value>. Confirm the contact count matches (or closely matches) the audience size in Zeotap.Important Notes and Limitations
Closed beta. The Hello Charles Batched Contacts API is in closed beta. You must have your Hello Charles success manager approve API access before this integration will work.
Email validation is lighter. Hello Charles is primarily used for WhatsApp activation, so email addresses are less strictly validated than phone numbers. They are still stored on the contact, but malformed emails are less likely to cause a sync failure.
Tags must exist in Hello Charles before they are sent. If you map a tag value that does not yet exist as a tag in Settings → Manage Tags, Hello Charles will not ingest it. Pre-create every tag you plan to send.
Custom property keys must match technical names exactly. When you create a custom property in Hello Charles, it has a display name and a technical name (the internal key). Use the technical name in your Zeotap mapping — not the display name.
Batch size. Each request to Hello Charles supports up to 1,000 contacts. For audiences larger than 1,000, Zeotap automatically splits the payload into multiple sequential requests.
Upsert semantics. Existing contacts are matched on External Reference Id and updated in place. If you want to add tags to contacts that already exist in Hello Charles, you can map just the External Reference Id and Tags — phone, email, and name are not required.
Closed-beta endpoints may change. Because the API is in closed beta, behaviours such as rate limits, field semantics, or response shapes may evolve. Confirm with your Hello Charles success manager if you see unexpected results.