KaiCalls Sms API

openapi: 3.2.0
info:
  title: KaiCalls Public Sms 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: SMS
paths:
  /v1/sms/messages:
    get:
      summary: List business-scoped SMS messages, including definitive failed send attempts
      description: Requires sms:read. Successful messages and provider-rejected outbound attempts share one evidence stream. Every row includes status, to, and timestamp; failed rows have status "failed" and a provider code. A null code means no definitive provider failure was recorded. Compliance-blocked requests are not provider send attempts and therefore do not create failed message rows.
      parameters:
      - name: conversation_id
        in: query
        required: false
        schema:
          type: string
      - name: direction
        in: query
        required: false
        schema:
          type: string
          enum:
          - inbound
          - outbound
      - name: after
        in: query
        required: false
        schema:
          type: string
          format: date-time
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
      responses:
        '200':
          description: SMS message evidence, including successful and failed attempts.
          content:
            application/json:
              schema:
                type: object
                required:
                - messages
                - has_more
                properties:
                  messages:
                    type: array
                    items:
                      type: object
                      required:
                      - status
                      - code
                      - to
                      - timestamp
                      properties:
                        status:
                          type: string
                        code:
                          type:
                          - string
                          - 'null'
                          description: Provider error code for a definitive failed send; null otherwise.
                        to:
                          type:
                          - string
                          - 'null'
                          description: Destination number.
                        timestamp:
                          type:
                          - string
                          - 'null'
                          format: date-time
                          description: Failure time, send time, or creation time, in that precedence order.
                        error_message:
                          type:
                          - string
                          - 'null'
                      additionalProperties: true
                  has_more:
                    type: boolean
      x-required-scopes: sms:read
      tags:
      - SMS
      operationId: getV1SmsMessages
      x-operation-id-source: derived
  /v1/sms/conversations:
    get:
      summary: List or retrieve SMS conversation threads
      responses:
        '200':
          description: SMS conversation list or object
      x-required-scopes: sms:read
      tags:
      - SMS
      operationId: getV1SmsConversations
      x-operation-id-source: derived
  /v1/sms/send:
    post:
      summary: Send an outbound SMS message from a workspace number (sms:write)
      description: 'The text goes out on the workspace''s own number through KaiCalls'' carriers. The destination needs usable SMS consent for the workspace. A customer-requested website booking confirmation can record that consent and send in one request: add purpose: booking_confirmation and the form''s actual sms_consent: true (or sms_opt_in: yes), with an Idempotency-Key. This narrow immediate-response path permits the requested confirmation after hours and still honors explicit opt-outs, DNC, content and rate limits. For a booking notification to this business''s active admin phone, use purpose: booking_alert with an Idempotency-Key. Ordinary messages may use dispatch_policy: queue_if_needed; 202 means queued, not sent. Imported walk-up clients become eligible only after POST /v1/leads records verified opt-in provenance; a cold phone number remains blocked. If the carrier definitively rejects an attempt, the error response includes attempt { code, to, timestamp }, and the same failed attempt is available from GET /v1/sms/messages with status "failed".'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - to
              - from_agent_id
              - message
              properties:
                to:
                  type: string
                  description: Destination in E.164 format.
                from_agent_id:
                  type: string
                  format: uuid
                message:
                  type: string
                  minLength: 1
                lead_id:
                  type: string
                  format: uuid
                idempotency_key:
                  type: string
                purpose:
                  type: string
                  enum:
                  - booking_confirmation
                  - booking_alert
                sms_consent:
                  type: boolean
                  description: Actual service-message consent captured by the form; required for booking_confirmation.
                sms_opt_in:
                  type: string
                  description: Accepted form-consent alias, for example yes.
                consent_language:
                  type: string
                  description: Disclosure shown on the form, when available.
                source_url:
                  type: string
                  format: uri
                  description: Optional HTTPS form URL for consent provenance.
                submission_id:
                  type: string
                  description: Original submission ID; defaults to the idempotency key.
                submitted_at:
                  type: string
                  format: date-time
                  description: Original submission time, if available. Immediate replies require a recent request.
                dispatch_policy:
                  type: string
                  enum:
                  - send_now
                  - queue_if_needed
      responses:
        '200':
          description: SMS accepted by the provider.
        '202':
          description: SMS queued for scheduled_for; includes queue_id. No carrier delivery is claimed.
        '400':
          description: 'Invalid or compliance-blocked request: consent_required means no recorded opt-in; number_opted_out means explicit opt-out. Also used for definitive provider rejection. A provider rejection includes attempt.code, attempt.to, and attempt.timestamp.'
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: object
                    required:
                    - code
                    - message
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                  attempt:
                    type: object
                    description: Present only when the provider definitively rejected an attempted send.
                    required:
                    - code
                    - to
                    - timestamp
                    properties:
                      code:
                        type: string
                      to:
                        type: string
                      timestamp:
                        type: string
                        format: date-time
        '409':
          description: Idempotency key reused with a different message request; do not treat as sent.
        '502':
          description: Provider outcome unknown; safe reconciliation is required.
        '503':
          description: Consent/suppression or intent verification unavailable; no successful send established.
      x-required-scopes: sms:write
      tags:
      - SMS
      operationId: postV1SmsSend
      x-operation-id-source: derived
  /v1/sms/update-prompt:
    post:
      summary: Update the SMS auto-reply prompt for a workspace's messaging
      responses:
        '200':
          description: Updated SMS prompt
      x-required-scopes: agents:write
      tags:
      - SMS
      operationId: postV1SmsUpdatePrompt
      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.