Integrate a phone platform

Overview

This resource will help you as you build an integration between a phone or voice platform and Klaviyo. It walks through why call data belongs in Klaviyo, the recommended integration flow, the call events to send, the optional profile properties to sync, and the authentication and certification requirements, with an API quick reference at the end.

Why connect your phone platform to Klaviyo

The phone is the highest-intent, highest-touch channel a brand has. A customer who calls is telling you exactly what they want in the moment, and a voice or AI-calling platform sits on top of that signal. The brands that get the most out of it don't leave that data trapped in a call log. They push it into the platform where they run every other channel. When that platform is Klaviyo and the data lives there natively, you get measurable wins:

• Call-driven segmentation. "Customers who called about order status in the last 7 days," "callers escalated to sales," "anyone with an unresolved call," "customers who left an after-hours voicemail." These behavioral audiences outperform list-only sends across every comparison we have.
• Post-call lifecycle moments. Call ended, intent detected, escalated to a human, follow-up SMS sent. These are some of the highest-converting triggers in the Klaviyo ecosystem because they fire at the moment of peak intent.
• Recover missed calls and deflect support volume. Proactive missed-call recovery, voicemail follow-up, and "we'll call you back" flows cut a measurable share of repeat-call and support-ticket volume across every phone integration we've looked at.
• Cross-channel attribution. Call events on the profile alongside email opens, SMS, and browse history let the merchant finally answer "did this call come from an email, an SMS, or a flow?" This is the strategic reason a CMO greenlights the integration.
• Stickier merchants. Phone data wired into automated flows is one of the strongest retention signals across the partner program. Merchants who build call-triggered flows rarely churn out of either platform.

Short version: call events and call state from your platform into the Klaviyo profile means the merchant's marketing and support teams can act on phone activity from the same place they run every other channel.

The flow

One-way push, partner to Klaviyo. Phone is event-driven. The value is in the moment of the call, not in persistent state, so events are the heart of this integration:

• Event emission for every call moment. Call started, intent detected, call ended, escalated, follow-up SMS sent, missed call, voicemail. These are the metrics the merchant builds segments and flows against.
• Profile property sync (optional) for last-call state. Last call status, last intent, last agent. Useful for "show me the current state of this caller" segmentation, written inline on the event so a single call covers both streams.

Both fire in real time as the call happens in your platform. Each profile is keyed by phone first for a phone integration, with email where you have it. This is the one place this guide differs from the commerce-driven guides: the phone number is the natural identity for a call, so lead with it. Use the merchant's customer ID as external_id where it's stable, but always identify by phone or email first.

On initial install, no historical backfill is needed for most use cases. Phone is forward-looking. If you do choose to backfill recent calls, scope it to a tight window (think 30 to 90 days) and use the bulk events job. Don't try to replay years of call history as events.

Events to send

Event names are not prefixed with your platform name. Branded events handle source attribution automatically when events flow through your OAuth token, so the metric name should just describe the action.

Use Title Case payload field names ("Call Duration", "Resolution Type") so they read cleanly in the Klaviyo property picker and template editor. If your platform emits raw snake_case keys internally (call_id, started_at, intent_confidence), map them to Title Case on the way out.

Events split into two tiers. Every integration should ship the core set. The recommended set significantly improves marketing and support workflows.

Core call events (minimum viable integration)

These enable the baseline use cases: trigger post-call flows, build segments on call activity, measure phone engagement, and attribute calls to campaigns and flows.

Recommended call events

These power highly targeted flows: missed-call recovery, voicemail follow-up, human-escalation journeys, and support-ticket follow-up sequences. AI-specific fields like Intent, Intent Confidence, and Resolution Type are some of the highest-value segmentation dimensions a phone integration can provide, so include them wherever you have them.

$value guidance: most call events are status updates, not revenue, so don't set $value on them. The exception is a call that directly produces an order (Call Handling Action with Action = create_order). Set $value to the order total there so the merchant sees revenue attribution per metric in Klaviyo reporting.

Attribution properties: if your platform can tie a call back to a marketing touch, include the standard Klaviyo attribution fields on the relevant event (Attributed Campaign, Attributed Flow, Attributed Message, Attributed Channel, Attributed Automation). This lets the merchant report calls alongside email and SMS touchpoints.

Profile properties to sync (optional)

Optional, but cheap to maintain since you can write them inline on any event. Use Title Case property names prefixed with your platform's name. Replace {Platform} below with the literal name of your platform (e.g., "Acme Last Call Status"). These give the merchant a current-state view of each caller for segmentation and personalization.

Implementation notes:

• Profile property writes go through Update Profile (PATCH /api/profiles/{id}/), or are written inline on Create Event (POST /api/events/). Inline on the event is the right default here.
• Pick property names up front and don't rename them. Renames break every segment, flow, and template that references them.
• Keep dates in ISO 8601 (UTC). Klaviyo treats string-typed dates as strings, which silently breaks date-property segmentation.
• Don't enrich profile name or address from the phone platform. The merchant's commerce integration (Shopify, BigCommerce, etc.) owns profile identity. Phone is the one identifier you legitimately own as a phone integration; stick to phone, email, and your call-state properties.

Auth, scopes, and certification

Build as a public OAuth app. Private API keys are a non-starter for the marketplace. Start with the Create a public OAuth app guide.

Key OAuth specifics for phone integrations:

• PKCE is required on the authorization code exchange (code_verifier must be included).
• Access tokens are short-lived (1 hour). Refresh tokens are long-lived but rotate on every use. Persist the latest refresh token after every refresh call, or you'll lose the integration on the next refresh.
• Tokens are scoped per Klaviyo account. Merchants with multiple Klaviyo accounts (brands, regions, prod and test) install separately for each.

Scopes to request:

• events:write for emitting call and SMS events. This is the core scope for a phone integration.
• profiles:write for writing the optional last-call properties to profiles.
• profiles:read only if your integration reads existing profile state (e.g., matching a caller to an existing profile before write). Most phone integrations don't need this. Don't over-scope. It gets flagged in marketplace review.

Branded metric badges happen automatically when events flow through the OAuth token. No extra payload field is needed. The integration source is identified by the token itself.

Once functional, submit for App Marketplace review. Plan for at least one round of feedback. The review covers OAuth, scopes, install and uninstall validation, and that the integration delivers what your listing claims.

API quick reference

Concrete specs for AI coding assistants and engineers grounding on this doc. The narrative above is the why and the flow. This section is the what-to-actually-type.

Headers (required on every request)

Authorization: Bearer <oauth_access_token>
revision: 2026-04-15
Accept: application/json
Content-Type: application/json

Pin the revision header to a specific date when you ship. Check the API versioning guide for the current latest. Without it you'll get a 400.

Event POST body

Send a call event. The event creates the profile if it doesn't exist, and updates the optional last-call properties on the profile inline. Identify by phone first, with email where you have it.

POST /api/events/

{
  "data": {
    "type": "event",
    "attributes": {
      "properties": {
        "Call ID": "call_8f21",
        "Call Duration": 342,
        "Status": "completed",
        "Resolution Type": "ai_resolved",
        "Intent": "order_status",
        "Agent": "virtual_agent",
        "Team": "support",
        "Summary": "Customer checked the status of order 1042."
      },
      "metric": {
        "data": {
          "type": "metric",
          "attributes": { "name": "Call Ended" }
        }
      },
      "profile": {
        "data": {
          "type": "profile",
          "attributes": {
            "phone_number": "+15555550100",
            "email": "[email protected]",
            "properties": {
              "{Platform} Last Call At": "2026-06-15T14:22:11Z",
              "{Platform} Last Call Status": "completed",
              "{Platform} Last Call Intent": "order_status"
            }
          }
        }
      }
    }
  }
}

Call that produces revenue

When a call directly results in an order, fire Call Handling Action and include $value so the merchant sees revenue attribution per metric in reporting.

POST /api/events/

{
  "data": {
    "type": "event",
    "attributes": {
      "properties": {
        "Call ID": "call_8f21",
        "Action": "create_order",
        "Order ID": "order_98765",
        "$value": 89.50
      },
      "metric": {
        "data": {
          "type": "metric",
          "attributes": { "name": "Call Handling Action" }
        }
      },
      "profile": {
        "data": {
          "type": "profile",
          "attributes": { "phone_number": "+15555550100" }
        }
      }
    }
  }
}

Retries

• 429: respect the Retry-After header. Otherwise exponential backoff starting at 1s, cap at 60s, max 5 retries.
• 5xx: same backoff.
• 4xx (other than 429): don't retry. Log and surface to the merchant.

Identifier guidance

• Identify by phone first for a phone integration; email where you have it. These are the fields Klaviyo merges on.
• external_id is NOT a merge key on its own. Use it as a secondary reference, pass it alongside phone or email, and store the merchant-side customer ID as a profile property (e.g., {Platform} Customer ID) for segmentation.
• If a call has neither a phone number nor an email, drop the event. Don't invent identity.

Rate limits

Per-account, not per-app. Standard limits handle typical call volume without effort. For merchants at unusual scale (think very high daily call and SMS volume), the path is per-endpoint, per-account increases through Klaviyo Support and CSM. Reach out before launch so we can fast-track the request rather than ramping into 429s in production.

Glossary

• Klaviyo profile: customer record. Keyed by email, phone, or external ID. For a phone integration, the caller.
• Klaviyo metric: event type. "Call Ended," "Call Intent Detected," etc. Created automatically on first event ingest.
• Klaviyo segment: dynamic audience computed from rules. The merchant builds these from your call events and properties to target callers.
• Klaviyo flow: automated journey, triggered by a metric (event) or segment membership. Where post-call, missed-call, and voicemail follow-ups live.
• Intent: the AI's classification of why the customer called (order status, pricing, support, etc.). A high-value segmentation dimension.
• Resolution type: how the call ended, AI resolved / human resolved / voicemail / missed. Drives escalation and recovery flows.

Resources

• Klaviyo Developer Portal. Start here for everything.
• Create a public OAuth app
• Create Event / Bulk Create Events / Update Profile
• Klaviyo App Marketplace. The existing set of integrations.