Marketing platforms
Customer.io has its own connection in Kontakt. Other marketing platforms and customer data platforms connect through building blocks that most of these tools already support.
Using Customer.io?
Many teams keep their existing marketing platform for email and in-app messages and add Kontakt for WhatsApp, AI agents, and conversational journeys. The two systems share data with plain HTTP:
| Direction | Building block | Best for |
|---|---|---|
| Your platform to Kontakt | Events API called from the platform's webhook action | Sending people and events with properties, traits, and idempotency |
| Your platform to Kontakt | Webhook source | Tools that can't add an Authorization header |
| Your platform to Kontakt | Send WhatsApp API called from the webhook action | Sending a WhatsApp template when your platform decides the timing |
| Kontakt to your platform | API Call journey step | Recording what happened in Kontakt, or updating an attribute |
| Kontakt to Customer.io | Customer.io connection | Replies, opt-outs, and template delivery as events, plus a Send to Customer.io journey step |
The examples below use placeholder variables such as {{customer.id}}. Replace them with your platform's own variable syntax.
Before you start
- An API key from Settings / API Keys. See Developers.
- Agree which identifier both systems share. Your own user ID is the most reliable. Send it as
user_id, and send phone in full international format when you want WhatsApp or SMS to reach the person. - Decide which system owns each event, so the same activity isn't recorded twice.
Send people and events into Kontakt
Most marketing platforms have a webhook or HTTP request action inside their journeys or campaigns. Point it at the events API:
Add a webhook action
In your platform's journey, add its webhook or HTTP request action. Set the method to POST and the URL to https://api.usekontakt.com/v1/events.
Add headers
Add Authorization: Bearer pk_live_your_key and Content-Type: application/json.
Write the body
{
"user_id": "{{customer.id}}",
"email": "{{customer.email}}",
"phone": "{{customer.phone}}",
"event": "activation_nudge",
"traits": {
"first_name": "{{customer.first_name}}",
"plan": "{{customer.plan}}"
},
"properties": { "journey": "activation", "step": "day_3" },
"idempotency_key": "{{event.id}}"
}Trigger a Kontakt journey
In Kontakt, create a journey triggered by the event activation_nudge. Each call creates or updates the person and starts the journey. See Journeys.
How Kontakt treats the call
- Creates or updates the person. If nobody matches
user_id,email, orphone, Kontakt creates them. Set"upsert_customer": falseto only record events for people who already exist. - Empty values are ignored. Many platforms render a missing attribute as an empty string. Kontakt skips empty traits, so they never wipe a field.
- Traits update the profile.
first_name,last_name,country,city, and similar keys update the matching profile fields. Other keys become custom fields. - WhatsApp opt-out. A
whatsapp_opt_intrait offalseopts the person out of WhatsApp marketing.trueopts them back in. - Tags. Send
tagsto add tags andremove_tagsto remove them, as an array or a comma-separated string. Tags that don't exist yet are created. - Local phone numbers. A number such as
08030000000is saved in full international format using the workspace country, so it matches the person's WhatsApp replies. See How Kontakt finds the person. - Retries are safe. With an
idempotency_key, a retried call returns the original event instead of recording a second one. Without one, Kontakt uses theIdempotency-Keyheader, or theX-CIO-Idempotency-Keyheader Customer.io sends.
For marketing consent on other channels, call POST /v1/consent. See Ingestion.
Send WhatsApp straight from your platform
When your platform's journey should send the WhatsApp message itself, point its webhook action at POST https://api.usekontakt.com/v1/messages/whatsapp instead of the events API. Send the person's identity, the template name, and its variables. Kontakt applies opt-outs and the contact policy, bills the message, and shows it in the inbox. See Send WhatsApp from your systems.
When your tool can't set headers
Use a webhook source instead. It needs no API key. It records one event name per source, finds the person from one field, and copies the payload fields you map into event properties.
Customer data platforms
Segment-style platforms send two kinds of calls: identify calls about who someone is, and track calls about what they did. If your platform can forward them to a custom HTTP destination or function, map them like this:
| Platform call | Kontakt endpoint | Notes |
|---|---|---|
| Identify, known user | POST /v1/customers | Send user_id, email, phone, and properties |
| Identify, anonymous visitor becomes known | POST /v1/identify | Send anonymous_id with user_id, email, or phone to merge their history |
| Track | POST /v1/events | Send the event name, identity, properties, and the platform's message ID as idempotency_key |
| Order completed | POST /v1/orders | Use for stores that are not connected to Kontakt directly |
Field details and examples are in Ingestion.
Send Kontakt activity back to your platform
For Customer.io, connect it under Settings / Connectors instead. See Customer.io. For other platforms: to record in your marketing platform that something happened in Kontakt, such as a customer replying on WhatsApp or a reward being sent, add an API Call step to the Kontakt journey at that point and call your platform's tracking or attribute API.
For example, a step with method POST, Authentication set to Bearer token, and this Request Body:
{
"email": "{{customer.email}}",
"event": "kontakt_whatsapp_sent",
"properties": { "journey": "activation" }
}
Journey steps can read the person's name, email, phone, Kontakt ID, custom fields, and the user ID your platform sent as {{customer.user_id}}.
Check your platform's API reference for the exact URL, authentication header, and body it expects. If it needs the key in a custom header, choose API key header and enter the header name.
Avoid double counting
If the same activity reaches Kontakt from more than one place, for example orders from a connected Shopify store and again from your platform, switch off the duplicate under Events / Sources. You can turn off a whole API key, or just one event from it. Kontakt then answers 202 with "ignored": true and records nothing. See Events.
What is not supported
- Connections for platforms other than Customer.io, OAuth installs, or audience sync with any marketing platform.
- Exporting Kontakt audiences to another platform automatically.
- Subscribing other platforms to Kontakt events. Use an API Call step for each thing you want to send. See Webhooks.
Troubleshooting
The call returns 401
The Authorization header is missing, misspelled, or the key was deleted or rotated. Create or rotate a key under Settings / API Keys.
The call returns 202 with ignored true
That API key, or this event from it, is switched off under Events / Sources.
People are duplicated between systems
The calls send different identifiers for the same person. Always include the shared user_id. Local phone numbers are saved with the workspace country code, so set the right country under Settings / Workspaces.
The journey didn't start
Check that the event name in the call matches the journey trigger exactly, including dots and underscores, and that the journey is active.