Conversations API overview

Before you begin

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

🚧

Access required

The Conversations API is available to approved OAuth applications and accounts only. To request access, submit this form. Access is granted either at the OAuth app level (for approved partners whose app is allow-listed across their install base) or at the account level (for customers requesting access for their own use). Private API keys are not supported; you must use an OAuth access token.

The Conversations API allows approved partners and businesses to send and retrieve conversation messages programmatically within the Klaviyo platform. It supports SMS and WhatsApp channels — the channel is determined automatically based on the conversation. This enables help desk and customer support integrations to participate in two-way conversations on behalf of Klaviyo accounts, using the account's existing Klaviyo sending number.

Use cases

Here are example use cases supported by the Conversations API:

• Integrate a helpdesk platform (e.g., Kustomer, Zowie, Crisp) so that support agents can reply to inbound SMS and WhatsApp messages from within their existing tooling.
• Build a custom support workflow that routes inbound messages to an internal queue and sends outbound replies via API.
• Retrieve a profile's full conversation history for context before responding.

Required scopes

To use Conversations API endpoints, your OAuth app will need the following scopes:

• conversations:write — required to send conversation messages
• conversations:read — required to retrieve conversation history
• profiles:read — required to retrieve conversation history via the Profiles API

Data model

Conversation message

The conversation-message resource represents a single message sent within a conversation thread. It has the following fields:

• body (attribute, required) — the text content of the message.
• conversation (relationship, required) — the conversation thread to send the message to.

Conversation

The conversation resource represents the full thread of messages exchanged between a Klaviyo account and a given profile on a single channel (SMS or WhatsApp). It can be retrieved directly via Get Conversation for Profile or included inline on a profile response using ?include=conversation.

How conversations are created

Conversations are created automatically by Klaviyo when a profile sends an inbound message — a customer texting your Klaviyo SMS number, or a customer messaging your WhatsApp Business number. There is no public API endpoint to create a conversation; one must already exist before you can send a reply.

This means:

• SMS: A conversation exists once a customer has texted your Klaviyo sending number.
• WhatsApp: A conversation exists once a customer has messaged your WhatsApp Business number. You cannot initiate a new WhatsApp conversation via API — the customer must message first.

Before calling Create Conversation Message, retrieve the conversation_id for the profile using Get Conversation for Profile. The conversation_id determines the channel — no channel field is needed in the request body.

Send a conversation message

Use Create Conversation Message to send an outbound message to a profile. The channel (SMS or WhatsApp) is determined automatically from the conversation_id — you do not specify the channel in the request.

Required fields

• conversation (relationship, required)

  The conversation to reply to. Use Get Conversation for Profile to retrieve the conversation_id for a profile. The channel (SMS or WhatsApp) is determined automatically from the conversation.

• body (required)

  The text content of the message. Maximum length is 1,600 characters for SMS and 1,024 characters for WhatsApp.

Example request

{
  "data": {
    "type": "conversation-message",
    "attributes": {
      "body": "Hi! Thanks for reaching out. How can we help you today?"
    },
    "relationships": {
      "conversation": {
        "data": {
          "type": "conversation",
          "id": "CONVERSATION_ID"
        }
      }
    }
  }
}

A successful response returns 202 Accepted with the created conversation-message object, including the message id.

Retrieve conversation history

Use Get Conversation for Profile to retrieve the full conversation thread for a given profile.

curl --request GET \
  'https://a.klaviyo.com/api/profiles/PROFILE_ID/conversation' \
  --header 'Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN' \
  --header 'revision: 2026-04-15'

You can also include the conversation inline when retrieving a profile using the include query parameter:

curl --request GET \
  'https://a.klaviyo.com/api/profiles/PROFILE_ID?include=conversation' \
  --header 'Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN' \
  --header 'revision: 2026-04-15'

Using webhooks to detect inbound messages

To reply to inbound messages in real time, subscribe to the event:klaviyo.sent_sms webhook topic using the Webhooks API. Despite the name, this event fires when a customer sends an SMS to your Klaviyo sending number — i.e., an inbound message that creates or continues a conversation. (The naming reflects the customer's action of sending, not Klaviyo's.)

📘

There is currently no equivalent webhook topic for inbound WhatsApp messages. If you are building a WhatsApp integration, you will need to poll Get Conversation for Profile to detect new inbound messages.

When an event:klaviyo.sent_sms webhook fires, the payload includes the Klaviyo profile ID of the sender:

{
  "data": {
    "type": "event",
    "attributes": {
      "event_properties": {
        "From Number": "+18108675309",
        "Message Body": "Hello, I need help with my order!"
      }
    },
    "relationships": {
      "profile": {
        "data": {
          "type": "profile",
          "id": "PROFILE_ID"
        }
      }
    }
  },
  "topic": "event:klaviyo.sent_sms"
}

The webhook payload does not include the conversation_id. Use the profile ID to retrieve it:

curl --request GET \
  'https://a.klaviyo.com/api/profiles/PROFILE_ID/conversation' \
  --header 'Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN' \
  --header 'revision: 2026-04-15'

Then use the returned conversation_id to send your reply with Create Conversation Message.

Full integration flow

1. Subscribe to event:klaviyo.sent_sms via the Webhooks API.
2. When a webhook fires, extract relationships.profile.data.id from the payload.
3. Call GET /api/profiles/{id}/conversation to retrieve the conversation_id.
4. Call POST /api/conversation-messages with the conversation_id and your reply body.

Rate limits

Conversations API endpoints use the SMALL rate limit tier: 3 requests/second burst and 60 requests/minute steady. See rate limits for more information.

Limitations

• Only OAuth access tokens are supported. Private API keys cannot be used with Conversations API endpoints.
• Only outbound messages can be sent via this API. Inbound messages (received from a profile) are accessible in the conversation history but cannot be created via API.
• Maximum message body length: 1,600 characters for SMS, 1,024 characters for WhatsApp.
• The profile must have a valid, consented phone number on the relevant channel. Attempting to send to a profile without consent will return a 400 error.
• The Klaviyo account must have the relevant channel (SMS or WhatsApp) configured and an active sending number.
• Access is gated at the OAuth app level or account level. See Before you begin for details on requesting access.

Troubleshooting

Additional resources

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