AgentPhone Conversations API

openapi: 3.2.0
info:
  title: SMS Conversations API
  description: A simple API to provision phone numbers and receive SMS
  version: 0.1.0
tags:
- name: Conversations
paths:
  /v1/conversations:
    get:
      tags:
      - Conversations
      summary: List Conversations
      description: 'List all conversations for this account.


        Sorted by most recent activity (lastMessageAt desc). `total` is served

        from a short per-account cache (app/services/conversation_totals.py);

        `hasMore` is computed from the page query itself.'
      operationId: list_conversations_v1_conversations_get
      security:
      - HTTPBearer: []
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          default: 20
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/app__routes__conversations__ConversationListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/conversations/{conversation_id}:
    get:
      tags:
      - Conversations
      summary: Get Conversation
      description: Get a conversation with its recent messages.
      operationId: get_conversation_v1_conversations__conversation_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: conversation_id
        in: path
        required: true
        schema:
          type: string
          title: Conversation Id
      - name: message_limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          default: 50
          title: Message Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationDetail'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Conversations
      summary: Update Conversation
      description: 'Update a conversation.


        - `metadata`: store custom context for AI agents (customer info, order/ticket

        ids, session state). Replaces the stored object; surfaced in webhook

        payloads as `conversationState`.

        - `group_name`: rename a group conversation (iMessage groups only). Also

        renames the underlying iMessage thread.


        Only the fields you include are changed: a rename-only PATCH leaves metadata

        untouched, and vice versa.'
      operationId: update_conversation_v1_conversations__conversation_id__patch
      security:
      - HTTPBearer: []
      parameters:
      - name: conversation_id
        in: path
        required: true
        schema:
          type: string
          title: Conversation Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateConversationRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationDetail'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/conversations/{conversation_id}/messages:
    get:
      tags:
      - Conversations
      summary: Get Conversation Messages
      description: 'Get paginated messages for a conversation.


        Use before/after for cursor-based pagination.'
      operationId: get_conversation_messages_v1_conversations__conversation_id__messages_get
      security:
      - HTTPBearer: []
      parameters:
      - name: conversation_id
        in: path
        required: true
        schema:
          type: string
          title: Conversation Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          default: 50
          title: Limit
      - name: before
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Before
      - name: after
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: After
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessagesListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/conversations/{conversation_id}/typing:
    post:
      tags:
      - Conversations
      summary: Send Typing Indicator
      description: 'Show a typing indicator in the conversation (iMessage only).


        Works for both 1:1 and group chats: a group id is itself a valid typing

        target, so every participant sees the indicator. Best-effort: the

        indicator may be silently dropped if the chat has no recent activity, the

        recipient isn''t on iMessage, or it''s RCS-routed (RCS carries no composing

        state). Auto-expires after a few seconds; no "stop typing" call needed.'
      operationId: send_typing_indicator_v1_conversations__conversation_id__typing_post
      security:
      - HTTPBearer: []
      parameters:
      - name: conversation_id
        in: path
        required: true
        schema:
          type: string
          title: Conversation Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendTypingResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/conversations/{conversation_id}/background:
    post:
      tags:
      - Conversations
      summary: Set Chat Background
      description: 'Set a custom wallpaper for the chat (iMessage only).


        Customer sends `image_url`; we fetch (≤10MB, JPEG/PNG/GIF/WebP/HEIC),

        validate, and forward as multipart to the iMessage provider. Idempotent —

        re-setting replaces. Recipients on iOS < 18 fall back to the default

        silently.'
      operationId: set_chat_background_v1_conversations__conversation_id__background_post
      security:
      - HTTPBearer: []
      parameters:
      - name: conversation_id
        in: path
        required: true
        schema:
          type: string
          title: Conversation Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetBackgroundRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetBackgroundResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Conversations
      summary: Remove Chat Background
      description: 'Clear the custom wallpaper for the chat (iMessage only).


        Idempotent: deleting a default-background chat returns 204 (no-op).'
      operationId: remove_chat_background_v1_conversations__conversation_id__background_delete
      security:
      - HTTPBearer: []
      parameters:
      - name: conversation_id
        in: path
        required: true
        schema:
          type: string
          title: Conversation Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    SendTypingResponse:
      properties:
        conversationId:
          type: string
          title: Conversationid
        channel:
          type: string
          title: Channel
        status:
          type: string
          title: Status
      type: object
      required:
      - conversationId
      - channel
      - status
      title: SendTypingResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ReplyToInConversation:
      properties:
        messageId:
          type: string
          title: Messageid
        message:
          type: string
          title: Message
        mediaUrls:
          items:
            type: string
          type: array
          title: Mediaurls
          default: []
      type: object
      required:
      - messageId
      - message
      title: ReplyToInConversation
    app__routes__conversations__ConversationListResponse:
      properties:
        data:
          items:
            $ref: '#/components/schemas/app__routes__conversations__ConversationSummary'
          type: array
          title: Data
        hasMore:
          type: boolean
          title: Hasmore
        total:
          type: integer
          title: Total
          description: Total conversations for this account; may be up to a few minutes old (cached per account, default five minutes). Use hasMore for pagination.
      type: object
      required:
      - data
      - hasMore
      - total
      title: ConversationListResponse
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    SetBackgroundResponse:
      properties:
        conversationId:
          type: string
          title: Conversationid
        channel:
          type: string
          title: Channel
        hasBackground:
          type: boolean
          title: Hasbackground
        backgroundId:
          anyOf:
          - type: string
          - type: 'null'
          title: Backgroundid
        backgroundVersion:
          anyOf:
          - type: integer
          - type: 'null'
          title: Backgroundversion
        changed:
          type: boolean
          title: Changed
      type: object
      required:
      - conversationId
      - channel
      - hasBackground
      - changed
      title: SetBackgroundResponse
    ReactionInConversation:
      properties:
        id:
          type: string
          title: Id
        reactionType:
          type: string
          title: Reactiontype
        fromNumber:
          type: string
          title: Fromnumber
        direction:
          type: string
          title: Direction
        createdAt:
          type: string
          format: date-time
          title: Createdat
      type: object
      required:
      - id
      - reactionType
      - fromNumber
      - direction
      - createdAt
      title: ReactionInConversation
    ConversationCapabilities:
      properties:
        canSendMessages:
          type: boolean
          title: Cansendmessages
        sendDisabledReason:
          anyOf:
          - type: string
          - type: 'null'
          title: Senddisabledreason
        sendChannel:
          anyOf:
          - type: string
          - type: 'null'
          title: Sendchannel
        availableChannels:
          items:
            type: string
          type: array
          title: Availablechannels
          default: []
        mediaChannels:
          items:
            type: string
          type: array
          title: Mediachannels
          default: []
        whatsappWindowExpiresAt:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Whatsappwindowexpiresat
        media:
          type: boolean
          title: Media
        reactions:
          type: boolean
          title: Reactions
        emojiReactions:
          type: boolean
          title: Emojireactions
      type: object
      required:
      - canSendMessages
      - media
      - reactions
      - emojiReactions
      title: ConversationCapabilities
      description: 'What the caller can do in this conversation, derived from its number''s

        provider and compliance state. Drives the dashboard composer/reaction UI.'
    MessagesListResponse:
      properties:
        data:
          items:
            $ref: '#/components/schemas/MessageInConversation'
          type: array
          title: Data
        hasMore:
          type: boolean
          title: Hasmore
      type: object
      required:
      - data
      - hasMore
      title: MessagesListResponse
    app__routes__conversations__ConversationSummary:
      properties:
        id:
          type: string
          title: Id
        agentId:
          anyOf:
          - type: string
          - type: 'null'
          title: Agentid
        phoneNumberId:
          type: string
          title: Phonenumberid
        phoneNumber:
          type: string
          title: Phonenumber
        participant:
          type: string
          title: Participant
        channel:
          type: string
          title: Channel
          default: native
        isGroup:
          type: boolean
          title: Isgroup
          default: false
        groupId:
          anyOf:
          - type: string
          - type: 'null'
          title: Groupid
        groupName:
          anyOf:
          - type: string
          - type: 'null'
          title: Groupname
        groupIconUrl:
          anyOf:
          - type: string
          - type: 'null'
          title: Groupiconurl
        participants:
          anyOf:
          - items:
              $ref: '#/components/schemas/GroupParticipant'
            type: array
          - type: 'null'
          title: Participants
        lastMessageAt:
          type: string
          format: date-time
          title: Lastmessageat
        lastMessagePreview:
          type: string
          title: Lastmessagepreview
        messageCount:
          type: integer
          title: Messagecount
        metadata:
          anyOf:
          - type: object
          - type: 'null'
          title: Metadata
        createdAt:
          type: string
          format: date-time
          title: Createdat
      type: object
      required:
      - id
      - phoneNumberId
      - phoneNumber
      - participant
      - lastMessageAt
      - lastMessagePreview
      - messageCount
      - createdAt
      title: ConversationSummary
    GroupParticipant:
      properties:
        identifier:
          type: string
          title: Identifier
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
      type: object
      required:
      - identifier
      title: GroupParticipant
      description: A member of a group chat, mirrored from Conversation.participants.
    UpdateConversationRequest:
      properties:
        metadata:
          anyOf:
          - type: object
          - type: 'null'
          title: Metadata
        group_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Group Name
          description: New display name for a group conversation. iMessage groups only; also renames the underlying iMessage thread. Ignored (omit) for 1:1 chats.
          examples:
          - Weekend Trip
      type: object
      title: UpdateConversationRequest
      description: Request body for updating a conversation.
    ConversationDetail:
      properties:
        id:
          type: string
          title: Id
        agentId:
          anyOf:
          - type: string
          - type: 'null'
          title: Agentid
        phoneNumberId:
          type: string
          title: Phonenumberid
        phoneNumber:
          type: string
          title: Phonenumber
        participant:
          type: string
          title: Participant
        channel:
          type: string
          title: Channel
          default: native
        isGroup:
          type: boolean
          title: Isgroup
          default: false
        groupId:
          anyOf:
          - type: string
          - type: 'null'
          title: Groupid
        groupName:
          anyOf:
          - type: string
          - type: 'null'
          title: Groupname
        groupIconUrl:
          anyOf:
          - type: string
          - type: 'null'
          title: Groupiconurl
        participants:
          anyOf:
          - items:
              $ref: '#/components/schemas/GroupParticipant'
            type: array
          - type: 'null'
          title: Participants
        lastMessageAt:
          type: string
          format: date-time
          title: Lastmessageat
        messageCount:
          type: integer
          title: Messagecount
        metadata:
          anyOf:
          - type: object
          - type: 'null'
          title: Metadata
        createdAt:
          type: string
          format: date-time
          title: Createdat
        messages:
          items:
            $ref: '#/components/schemas/MessageInConversation'
          type: array
          title: Messages
        capabilities:
          anyOf:
          - $ref: '#/components/schemas/ConversationCapabilities'
          - type: 'null'
      type: object
      required:
      - id
      - phoneNumberId
      - phoneNumber
      - participant
      - lastMessageAt
      - messageCount
      - createdAt
      - messages
      title: ConversationDetail
    MessageInConversation:
      properties:
        id:
          type: string
          title: Id
        body:
          type: string
          title: Body
        fromNumber:
          type: string
          title: Fromnumber
        toNumber:
          type: string
          title: Tonumber
        direction:
          type: string
          title: Direction
        senderIdentifier:
          anyOf:
          - type: string
          - type: 'null'
          title: Senderidentifier
        channel:
          anyOf:
          - type: string
          - type: 'null'
          title: Channel
        status:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
        failureReason:
          anyOf:
          - type: string
          - type: 'null'
          title: Failurereason
        errorCode:
          anyOf:
          - type: string
          - type: 'null'
          title: Errorcode
        deliveredAt:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Deliveredat
        deliveredChannel:
          anyOf:
          - type: string
          - type: 'null'
          title: Deliveredchannel
        readAt:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Readat
        mediaUrl:
          anyOf:
          - type: string
          - type: 'null'
          title: Mediaurl
        mediaUrls:
          items:
            type: string
          type: array
          title: Mediaurls
          default: []
        receivedAt:
          type: string
          format: date-time
          title: Receivedat
        content:
          anyOf:
          - type: object
          - type: 'null'
          title: Content
        reactions:
          items:
            $ref: '#/components/schemas/ReactionInConversation'
          type: array
          title: Reactions
          default: []
        replyTo:
          anyOf:
          - $ref: '#/components/schemas/ReplyToInConversation'
          - type: 'null'
      type: object
      required:
      - id
      - body
      - fromNumber
      - toNumber
      - direction
      - receivedAt
      title: MessageInConversation
    SetBackgroundRequest:
      properties:
        image_url:
          type: string
          title: Image Url
          description: HTTPS URL of the background image. JPEG/PNG/GIF/WebP/HEIC, max 10MB. Recipients on iOS < 18 see the default background; no error is raised.
          examples:
          - https://example.com/wallpaper.jpg
      type: object
      required:
      - image_url
      title: SetBackgroundRequest
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer