Skip to content

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?

Start with Customer.io. It sends WhatsApp replies, opt-outs, and delivery back to Customer.io without any journey steps.

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:

DirectionBuilding blockBest for
Your platform to KontaktEvents API called from the platform's webhook actionSending people and events with properties, traits, and idempotency
Your platform to KontaktWebhook sourceTools that can't add an Authorization header
Your platform to KontaktSend WhatsApp API called from the webhook actionSending a WhatsApp template when your platform decides the timing
Kontakt to your platformAPI Call journey stepRecording what happened in Kontakt, or updating an attribute
Kontakt to Customer.ioCustomer.io connectionReplies, 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, or phone, Kontakt creates them. Set "upsert_customer": false to 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_in trait of false opts the person out of WhatsApp marketing. true opts them back in.
  • Tags. Send tags to add tags and remove_tags to 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 08030000000 is 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 the Idempotency-Key header, or the X-CIO-Idempotency-Key header 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 callKontakt endpointNotes
Identify, known userPOST /v1/customersSend user_id, email, phone, and properties
Identify, anonymous visitor becomes knownPOST /v1/identifySend anonymous_id with user_id, email, or phone to merge their history
TrackPOST /v1/eventsSend the event name, identity, properties, and the platform's message ID as idempotency_key
Order completedPOST /v1/ordersUse 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.