KaiCalls Messages API

openapi: 3.2.0
info:
  title: KaiCalls Public Messages API
  version: '2026-06-05'
  description: Machine-readable surface for KaiCalls external developers and client agents.
servers:
- url: https://www.kaicalls.com/api
security:
- bearerAuth: []
tags:
- name: Messages
paths:
  /v1/messages:
    post:
      summary: Send one text or WhatsApp message as the business (sms:write).
      description: 'One send endpoint for texts and WhatsApp. sms goes out from the agent''s own line (from_agent_id required) with the same gates and error codes as POST /v1/sms/send. whatsapp goes out from the business''s number connected to WhatsApp (pass from when there is more than one) and only inside the 24-hour window after the customer last messaged that number; WhatsApp consent and Do-Not-Call are checked first. Email is not sent here: channel email is 400 use_email_campaigns. API email goes out as a campaign the business owner reviews and approves, through POST /v1/email-campaigns. Send Idempotency-Key (or idempotency_key) to make a retry return the original send (replayed: true) instead of sending again; the same key with a different message is 409 idempotency_conflict. New keyed WhatsApp sends claim a durable intent before dispatch; concurrent or uncertain replays never dispatch again. A 409 message_outcome_unknown requires reconciliation, not a new key. Pre-existing lost receipts cannot be recovered. 503 idempotency_unavailable means reservation or replay evidence could not be verified. A 200 means the provider accepted the message, not that it was delivered.'
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - channel
              - to
              - body
              properties:
                channel:
                  type: string
                  enum:
                  - sms
                  - whatsapp
                  description: email is refused with 400 use_email_campaigns.
                to:
                  type: string
                  description: E.164 phone number.
                body:
                  type: string
                  minLength: 1
                  description: 'Alias: message.'
                business_id:
                  type: string
                  format: uuid
                  description: Required when the API key reaches more than one business.
                from_agent_id:
                  type: string
                  format: uuid
                  description: sms only, required there.
                from:
                  type: string
                  description: 'whatsapp only: the business''s connected WhatsApp number.'
                lead_id:
                  type: string
                  format: uuid
                idempotency_key:
                  type: string
      responses:
        '200':
          description: Accepted by the provider.
          content:
            application/json:
              schema:
                type: object
                required:
                - id
                - channel
                - status
                - to
                - from
                properties:
                  id:
                    type: string
                  channel:
                    type: string
                    enum:
                    - sms
                    - whatsapp
                  status:
                    type: string
                    enum:
                    - sent
                    - queued
                  to:
                    type: string
                  from:
                    type: string
                  provider:
                    type: string
                  replayed:
                    type: boolean
        '400':
          description: 'Invalid request or a compliance block: bad_request, use_email_campaigns, business_id_required, from_required, automation_paused, number_opted_out, number_on_dnc, content_blocked, tcpa_violation, rate_limit_exceeded.'
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: object
                    required:
                    - code
                    - message
                    properties:
                      code:
                        type: string
                      message:
                        type: string
        '403':
          description: Missing sms:write scope, or no access to business_id (forbidden).
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: object
                    required:
                    - code
                    - message
                    properties:
                      code:
                        type: string
                      message:
                        type: string
        '404':
          description: Agent or lead not found (not_found).
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: object
                    required:
                    - code
                    - message
                    properties:
                      code:
                        type: string
                      message:
                        type: string
        '409':
          description: whatsapp_not_connected, whatsapp_window_closed, idempotency_conflict, message_outcome_unknown.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: object
                    required:
                    - code
                    - message
                    properties:
                      code:
                        type: string
                      message:
                        type: string
        '502':
          description: 'Provider failure: sms_send_failed, whatsapp_send_failed, outcome_unknown.'
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: object
                    required:
                    - code
                    - message
                    properties:
                      code:
                        type: string
                      message:
                        type: string
        '503':
          description: 'idempotency_unavailable: WhatsApp replay evidence cannot be verified; no new send.'
      x-required-scopes: sms:write
      tags:
      - Messages
      operationId: postV1Messages
      x-operation-id-source: derived
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'KaiCalls API key. Per-operation scope requirements are published on each operation as `x-required-scopes` — a scope string, or a nested `{ allOf: [...] }` / `{ anyOf: [...] }` expression. An operation with no `x-required-scopes` requires a valid key but no particular scope.'
      x-scopes:
      - workspaces:read
      - workspaces:write
      - numbers:read
      - numbers:write
      - agents:read
      - agents:write
      - communication-runs:read
      - communication-runs:write
      - calls:read
      - calls:write
      - sms:read
      - sms:write
      - webhooks:read
      - webhooks:write
      - events:read
      - events:replay
      - lifecycle:write
      - leads:read
      - leads:write
      - emails:read
      - emails:write
      - sdr:read
      - sdr:write
      - evals:read
      - evals:write
      - appointments:read
      - appointments:write
      - knowledge:read
      - knowledge:write
      - products:read
      - products:write
      - integrations:write
      - approvals:write
      - concierge:write
      - billing:read
      - billing:write
      - call_evidence:read
      - call_evidence:write
      - support:write
    sessionAuth:
      type: apiKey
      in: cookie
      name: sb-access-token
      description: Authenticated dashboard session cookie. Used by first-party flows that mint or manage API keys.