Sinch Conversations API

openapi: 3.2.0
info:
  title: Sinch Conversation Conversations API
  description: The Sinch Conversation API is an omnichannel messaging platform that enables developers to send and receive messages across multiple channels including SMS, RCS, WhatsApp, Facebook Messenger, Instagram, Viber, Telegram, KakaoTalk, and LINE through a single unified API. It provides contact management, conversation tracking, message templating, and webhook callbacks for real-time event handling. The API normalizes message formats across channels, allowing developers to build multichannel messaging experiences without channel-specific integrations.
  version: '1.0'
  contact:
    name: Sinch Support
    url: https://www.sinch.com/contact-us/
  termsOfService: https://www.sinch.com/terms-of-service/
servers:
- url: https://us.conversation.api.sinch.com
  description: US Production Server
- url: https://eu.conversation.api.sinch.com
  description: EU Production Server
- url: https://br.conversation.api.sinch.com
  description: Brazil Production Server
security:
- oAuth2: []
- basicAuth: []
tags:
- name: Conversations
  description: Manage conversations which are collections of messages tied to a specific app and contact.
paths:
  /v1/projects/{project_id}/conversations:
    get:
      operationId: listConversations
      summary: List Conversations
      description: Returns a list of conversations for a project with optional filtering.
      tags:
      - Conversations
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - name: only_active
        in: query
        description: Only return active conversations
        schema:
          type: boolean
      - name: app_id
        in: query
        description: Filter by app ID
        schema:
          type: string
      - name: contact_id
        in: query
        description: Filter by contact ID
        schema:
          type: string
      - name: page_size
        in: query
        description: The number of conversations per page
        schema:
          type: integer
          default: 10
      - name: page_token
        in: query
        description: Pagination token for the next page
        schema:
          type: string
      responses:
        '200':
          description: List of conversations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationList'
        '401':
          description: Unauthorized
    post:
      operationId: createConversation
      summary: Create a Conversation
      description: Creates a new conversation associated with a contact and app.
      tags:
      - Conversations
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateConversationRequest'
      responses:
        '200':
          description: Conversation created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
  /v1/projects/{project_id}/conversations/{conversation_id}:
    get:
      operationId: getConversation
      summary: Get a Conversation
      description: Returns the details of a specific conversation.
      tags:
      - Conversations
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ConversationId'
      responses:
        '200':
          description: Conversation details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
        '401':
          description: Unauthorized
        '404':
          description: Conversation not found
    patch:
      operationId: updateConversation
      summary: Update a Conversation
      description: Updates the properties of a specific conversation.
      tags:
      - Conversations
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ConversationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateConversationRequest'
      responses:
        '200':
          description: Conversation updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
        '401':
          description: Unauthorized
        '404':
          description: Conversation not found
    delete:
      operationId: deleteConversation
      summary: Delete a Conversation
      description: Deletes a specific conversation and optionally its messages.
      tags:
      - Conversations
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ConversationId'
      responses:
        '200':
          description: Conversation deleted
        '401':
          description: Unauthorized
        '404':
          description: Conversation not found
  /v1/projects/{project_id}/conversations/{conversation_id}:stop:
    post:
      operationId: stopConversation
      summary: Stop a Conversation
      description: Stops an active conversation, marking it as inactive.
      tags:
      - Conversations
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ConversationId'
      responses:
        '200':
          description: Conversation stopped
        '401':
          description: Unauthorized
        '404':
          description: Conversation not found
components:
  schemas:
    UpdateConversationRequest:
      type: object
      properties:
        active:
          type: boolean
          description: Updated active status
        active_channel:
          type: string
          description: Updated active channel
        metadata:
          type: string
          description: Updated metadata
    Conversation:
      type: object
      properties:
        id:
          type: string
          description: The unique conversation identifier
        app_id:
          type: string
          description: The app ID
        contact_id:
          type: string
          description: The contact ID
        active:
          type: boolean
          description: Whether the conversation is active
        active_channel:
          type: string
          description: The currently active channel
        metadata:
          type: string
          description: Conversation metadata
        metadata_json:
          type: object
          description: Structured conversation metadata
    CreateConversationRequest:
      type: object
      required:
      - app_id
      - contact_id
      properties:
        app_id:
          type: string
          description: The app ID
        contact_id:
          type: string
          description: The contact ID
        active:
          type: boolean
          description: Whether the conversation is active
          default: true
        active_channel:
          type: string
          description: The active channel
        metadata:
          type: string
          description: Conversation metadata
    ConversationList:
      type: object
      properties:
        conversations:
          type: array
          description: List of conversations
          items:
            $ref: '#/components/schemas/Conversation'
        next_page_token:
          type: string
          description: Pagination token for the next page
  parameters:
    ProjectId:
      name: project_id
      in: path
      required: true
      description: The unique project identifier
      schema:
        type: string
    ConversationId:
      name: conversation_id
      in: path
      required: true
      description: The unique conversation identifier
      schema:
        type: string
  securitySchemes:
    oAuth2:
      type: oauth2
      description: OAuth 2.0 client credentials flow using project key ID and secret.
      flows:
        clientCredentials:
          tokenUrl: https://auth.sinch.com/oauth2/token
          scopes: {}
    basicAuth:
      type: http
      scheme: basic
      description: Key ID as username and key secret as password.
externalDocs:
  description: Sinch Conversation API Documentation
  url: https://developers.sinch.com/docs/conversation