Get started with the Conversations API

When a brand uses Klaviyo for SMS and WhatsApp marketing, customers text back with questions about orders, sizing, and returns. Those replies land in Klaviyo, but many brands handle support in a separate help desk tool (Zowie, Kustomer, Richpanel, Crisp, Gorgias, and others).

The Conversations API is the bridge between the two. It lets an approved help desk or platform reply to a customer through the brand's existing Klaviyo SMS number or WhatsApp sender. The customer sees one continuous thread from one number, while support happens in the help desk.

📘

The Conversations API sends replies into an existing conversation. To retrieve the full history of messages exchanged with a customer, use the Events API.

Before you begin

You'll need:

• The Conversations API enabled for your account or app (see Request access below).
• A help desk or platform that will send the replies.
• A Klaviyo SMS or WhatsApp sender that the brand already uses.

Also check out our general API overview to make sure you're ready to get started with specific endpoints.

How it works

The same flow applies to SMS and WhatsApp:

1. The customer messages the brand's Klaviyo SMS number or WhatsApp sender.
2. Klaviyo notifies the help desk with a webhook.
3. The help desk looks up the conversation's ID for that customer.
4. An agent replies, and the help desk sends that reply to the conversation.
5. Klaviyo accepts the message immediately with a 202 Accepted response — accepted, but not yet delivered.
6. The customer receives the reply in the same thread, and Klaviyo reports delivered or failed back to the help desk via webhook.

Request access

The Conversations API is gated: Klaviyo enables it per account or per partner app, and it isn't on by default. Without it enabled, sending a message returns a 403 error. Looking up a conversation does not require this same enablement.

To request access, contact your Klaviyo representative or submit this form. Requests may include a short security review before access is granted.

Authentication

Choose one:

• Private key — send Authorization: Klaviyo-API-Key pk_your_private_key.
• OAuth — build a public OAuth app, obtain an access token through Klaviyo's authorization-code flow, then send Authorization: Bearer your-access-token. See Set up OAuth and Create a public OAuth app.

Scopes

• profiles:read and conversations:read to look up a conversation ID.
• conversations:write to send a message.

Set up a test conversation

Before you begin, you'll need a conversation in your test account.

For SMS:

1. Text "JOIN" then "YES" to your Klaviyo sending number.
2. Text an unrecognized phrase, such as "I'm having trouble with my order, can you help me?", to your Klaviyo sending number.

For WhatsApp, start a conversation with your WhatsApp sender the same way.

To find your sending number, go to Account > Settings, then SMS settings or WhatsApp settings.

Step 1: Retrieve a conversation ID

You need a conversation ID to send a message. Use whichever method below matches how you identify the customer — both return conversations across all channels, each with a channel attribute of sms or whatsapp.

By profile ID

curl --location 'https://a.klaviyo.com/api/profiles/01HMYC4DXNQKJFGXDC1493J4QZ/conversations/' \
  --header 'Authorization: Klaviyo-API-Key pk_your_private_key' \
  --header 'revision: 2026-07-15' \
  --header 'Accept: application/json'

{
  "data": [
    {
      "type": "conversation",
      "id": "01HQ71HFE865V215DE1CTEWH0A",
      "attributes": { "channel": "sms" },
      "relationships": {
        "profile": { "data": { "type": "profile", "id": "01HMYC4DXNQKJFGXDC1493J4QZ" } }
      },
      "links": { "self": null }
    },
    {
      "type": "conversation",
      "id": "01HQVNH9DN65R6PPG2X7R5JQC4",
      "attributes": { "channel": "whatsapp" },
      "relationships": {
        "profile": { "data": { "type": "profile", "id": "01HMYC4DXNQKJFGXDC1493J4QZ" } }
      },
      "links": { "self": null }
    }
  ],
  "links": {
    "self": "https://a.klaviyo.com/api/profiles/01HMYC4DXNQKJFGXDC1493J4QZ/conversations/"
  }
}

By email

curl --location 'https://a.klaviyo.com/api/profiles/?filter=equals(email,%[email protected]%22)&include=conversations' \
  --header 'Authorization: Klaviyo-API-Key pk_your_private_key' \
  --header 'revision: 2026-07-15' \
  --header 'Accept: application/json'

Look up a profile by email and get its conversations in the top-level included array. This can return more than one profile and conversation, since email addresses are not unique. See Get Profiles for more.

📘

To read the messages exchanged in a conversation (its history), use the Events API — look for Sent SMS and Received SMS events.

Step 2: Send a conversation message

Send a message to the conversation ID from Step 1 — here, the SMS conversation retrieved above.

curl --request POST \
  --url https://a.klaviyo.com/api/conversation-messages/ \
  --header 'Authorization: Klaviyo-API-Key pk_your_private_key' \
  --header 'revision: 2026-07-15' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "data": {
      "type": "conversation-message",
      "attributes": { "body": "Let me look into that for you! -Thanks, Bobby" },
      "relationships": {
        "conversation": { "data": { "type": "conversation", "id": "01HQ71HFE865V215DE1CTEWH0A" } }
      }
    }
  }'

{
  "data": {
    "type": "conversation-message",
    "id": "01HQB9CKDTBRZWPHCATWVWA70B",
    "attributes": {}
  }
}

A 202 Accepted response means the message was accepted, not that it was delivered. Klaviyo reports final delivery or failure via webhook.

Common errors

Additional resources

• Conversations API overview
• Create Conversation Message
• Get Conversations for Profile
• Set up OAuth
• Rate limits, status codes, and errors