openapi: 3.0.0
servers:
  - url: https://api.nexmo.com/v0.2
info:
  contact:
    email: devrel@vonage.com
    name: Vonage DevRel
    url: https://developer.nexmo.com/
  description: The Conversation API enables you to build conversation features where communication can take place across multiple mediums including IP Messaging, PSTN Voice, SMS and WebRTC Audio and Video. The context of the conversations is maintained though each communication event taking place within a conversation, no matter the medium.
  title: Conversation API
  version: 1.0.1
  x-label: Beta
  x-logo:
    url: https://www.vonage.com/content/dam/vonage/us-en/api/illustrations/Mobile_APIs_Services.svg
  x-origin:
    - format: openapi
      url: https://raw.githubusercontent.com/nexmo/api-specification/master/definitions/conversation.v2.yml
      version: "3.0"
  x-providerName: nexmo.com
  x-serviceName: conversation.v2
tags:
  - description: A conversation is a shared core component that Vonage APIs rely on. Conversations happen over multiple mediums and and can have associated Users through Memberships.
    name: conversation
  - description: Memberships connect users with conversations. Each membership has one conversation and one user however a user can have many memberships to conversations just as conversations can have many members.
    name: member
  - description: "Events are actions that occur within a conversation. Examples of this includes: Text events from members, or invite events from users"
    name: event
paths:
  /conversations:
    get:
      description: |
        Please note that not all data is available in the list endpoint. Once 
        you've identified the conversation you need to work with, use the 
        [GET /conversations/:id](#get-conversation) endpoint to fetch all of the conversation details
      operationId: get-conversations
      parameters:
        - $ref: "#/components/parameters/page_size"
        - $ref: "#/components/parameters/order"
        - $ref: "#/components/parameters/cursor"
        - $ref: "#/components/parameters/date_start"
        - $ref: "#/components/parameters/date_end"
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  _embedded:
                    properties:
                      data:
                        properties:
                          conversations:
                            description: List of conversations matching the provided filter
                            items:
                              $ref: "#/components/schemas/conversation_list"
                            type: array
                        type: object
                    type: object
                    x-nexmo-developer-collection-description-shown: true
                  _links:
                    properties:
                      first:
                        properties:
                          href:
                            example: https://api.nexmo.com/v0.2/conversations?order=desc&page_size=10
                            type: string
                        type: object
                      next:
                        properties:
                          href:
                            example: https://api.nexmo.com/v0.2/conversations?order=desc&page_size=10&cursor=88b395c167da4d94e929705cbd63b829a650e69a39197bfd4c949f4243f60dc4babb696afa404d2f44e7775e32b967f2a1a0bb8fb259c0999ba5a4e501eaab55
                            type: string
                        type: object
                      prev:
                        properties:
                          href:
                            example: https://api.nexmo.com/v0.2/conversations?order=desc&page_size=10&cursor=069626a3de11d2ec900dff5042197bd75f1ce41dafc3f2b2481eb9151086e59aae9dba3e3a8858dc355232d499c310fbfbec43923ff657c0de8d49ffed9f7edb
                            type: string
                        type: object
                      self:
                        properties:
                          href:
                            example: https://api.nexmo.com/v0.2/conversations?order=desc&page_size=10&cursor=88b395c167da4d94e929705cbd63b82973771e7d390d274a58e301386d5762600a3ffd799bfb3fc5190c5a0d124cdd0fc72fe6e450506b18e4e2edf9fe84c7a0
                            type: string
                        type: object
                    type: object
                  cursor:
                    description: Current cursor
                    example: 88b395c167da4d94e929705cbd63b82973771e7d390d274a58e301386d5762600a3ffd799bfb3fc5190c5a0d124cdd0fc72fe6e450506b18e4e2edf9fe84c7a0
                    type: string
                  page_size:
                    description: The number of results returned on this page.
                    example: 10
                    type: integer
          description: OK
      summary: List Conversations
      tags:
        - conversation
  /conversations/{conversation_id}/events:
    get:
      operationId: get-events
      parameters:
        - $ref: "#/components/parameters/conversation_id_parameter"
        - $ref: "#/components/parameters/page_size"
        - $ref: "#/components/parameters/order"
        - $ref: "#/components/parameters/cursor"
        - $ref: "#/components/parameters/start_id_parameter"
        - $ref: "#/components/parameters/end_id_parameter"
        - $ref: "#/components/parameters/event_type_parameter"
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  _embedded:
                    properties:
                      data:
                        properties:
                          events:
                            description: List of events matching the provided filter
                            items:
                              $ref: "#/components/schemas/all_events"
                            type: array
                        type: object
                    type: object
                    x-nexmo-developer-collection-description-shown: true
                  _links:
                    properties:
                      first:
                        properties:
                          href:
                            example: https://api.nexmo.com/v0.2/conversations/CON-92a44c64-7e4e-485f-a0c4-1f2adfc44625/events?page_size=10
                            type: string
                        type: object
                      next:
                        properties:
                          href:
                            example: https://api.nexmo.com/v0.2/conversations/CON-92a44c64-7e4e-485f-a0c4-1f2adfc44625/events?page_size=10&cursor=4db03d9254d1cdaecc7b1fc15b6bf1a81f3d3151191d784f1327893f8dc96416
                            type: string
                        type: object
                      prev:
                        properties:
                          href:
                            example: https://api.nexmo.com/v0.2/conversations/CON-92a44c64-7e4e-485f-a0c4-1f2adfc44625/events?page_size=10&cursor=84963f79fd25785be9706bd38bfd30c264f71964fa4edc8d8b4dd5f30bbd9f7c
                            type: string
                        type: object
                      self:
                        properties:
                          href:
                            example: https://api.nexmo.com/v0.2/conversations/CON-92a44c64-7e4e-485f-a0c4-1f2adfc44625/events?page_size=10&cursor=a30e3b7a3dcda1434f64bbb1a5fa489b
                            type: string
                        type: object
                    type: object
                  page_size:
                    description: The number of results returned on this page.
                    example: 10
                    type: integer
          description: OK
      summary: List Events
      tags:
        - event
  /conversations/{conversation_id}/members:
    get:
      operationId: get-members
      parameters:
        - $ref: "#/components/parameters/conversation_id_parameter"
        - $ref: "#/components/parameters/page_size"
        - $ref: "#/components/parameters/order"
        - $ref: "#/components/parameters/cursor"
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  _embedded:
                    properties:
                      data:
                        properties:
                          members:
                            description: List of members matching the provided filter
                            items:
                              $ref: "#/components/schemas/member_list"
                            type: array
                        type: object
                    type: object
                    x-nexmo-developer-collection-description-shown: true
                  _links:
                    properties:
                      first:
                        properties:
                          href:
                            example: https://api.nexmo.com/v0.2/members?order=desc&page_size=10
                            type: string
                        type: object
                      next:
                        properties:
                          href:
                            example: https://api.nexmo.com/v0.2/members?order=desc&page_size=10&cursor=88b395c167da4d94e929705cbd63b829a650e69a39197bfd4c949f4243f60dc4babb696afa404d2f44e7775e32b967f2a1a0bb8fb259c0999ba5a4e501eaab55
                            type: string
                        type: object
                      prev:
                        properties:
                          href:
                            example: https://api.nexmo.com/v0.2/members?order=desc&page_size=10&cursor=069626a3de11d2ec900dff5042197bd75f1ce41dafc3f2b2481eb9151086e59aae9dba3e3a8858dc355232d499c310fbfbec43923ff657c0de8d49ffed9f7edb
                            type: string
                        type: object
                      self:
                        properties:
                          href:
                            example: https://api.nexmo.com/v0.2/members?order=desc&page_size=10&cursor=88b395c167da4d94e929705cbd63b82973771e7d390d274a58e301386d5762600a3ffd799bfb3fc5190c5a0d124cdd0fc72fe6e450506b18e4e2edf9fe84c7a0
                            type: string
                        type: object
                    type: object
                  page_size:
                    description: The number of results returned on this page
                    example: 10
                    type: integer
          description: OK
      summary: List Members
      tags:
        - member
  /users:
    get:
      operationId: get-users
      parameters:
        - $ref: "#/components/parameters/page_size"
        - $ref: "#/components/parameters/order"
        - $ref: "#/components/parameters/cursor"
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  _embedded:
                    properties:
                      data:
                        properties:
                          users:
                            description: List of users matching the provided filter
                            items:
                              $ref: "#/components/schemas/user_list"
                            type: array
                        type: object
                    type: object
                    x-nexmo-developer-collection-description-shown: true
                  _links:
                    properties:
                      first:
                        properties:
                          href:
                            example: https://api.nexmo.com/v0.2/users?order=desc&page_size=10
                            type: string
                        type: object
                      next:
                        properties:
                          href:
                            example: https://api.nexmo.com/v0.2/users?order=desc&page_size=10&cursor=88b395c167da4d94e929705cbd63b829a650e69a39197bfd4c949f4243f60dc4babb696afa404d2f44e7775e32b967f2a1a0bb8fb259c0999ba5a4e501eaab55
                            type: string
                        type: object
                      prev:
                        properties:
                          href:
                            example: https://api.nexmo.com/v0.2/users?order=desc&page_size=10&cursor=069626a3de11d2ec900dff5042197bd75f1ce41dafc3f2b2481eb9151086e59aae9dba3e3a8858dc355232d499c310fbfbec43923ff657c0de8d49ffed9f7edb
                            type: string
                        type: object
                      self:
                        properties:
                          href:
                            example: https://api.nexmo.com/v0.2/users?order=desc&page_size=10&cursor=88b395c167da4d94e929705cbd63b82973771e7d390d274a58e301386d5762600a3ffd799bfb3fc5190c5a0d124cdd0fc72fe6e450506b18e4e2edf9fe84c7a0
                            type: string
                        type: object
                    type: object
                  cursor:
                    description: Current cursor
                    example: 88b395c167da4d94e929705cbd63b82973771e7d390d274a58e301386d5762600a3ffd799bfb3fc5190c5a0d124cdd0fc72fe6e450506b18e4e2edf9fe84c7a0
                    type: string
                  page_size:
                    description: The number of results returned on this page
                    example: 10
                    type: integer
          description: OK
      summary: List Users
components:
  parameters:
    conversation_id_parameter:
      description: The ID of the conversation
      example: CON-afe887d8-d587-4280-9aae-dfa4c9227d5e
      in: path
      name: conversation_id
      required: true
      schema:
        type: string
    cursor:
      description: |
        The cursor to start returning results from.

        You are not expected to provide this manually, but to follow the url provided in `_links.next.href` in the response which contains a `cursor` value
      in: query
      name: cursor
      required: false
      schema:
        type: string
    date_end:
      description: Search for conversations created before this ISO8601 date
      in: query
      name: date_end
      required: false
      schema:
        type: string
    date_start:
      description: Search for conversations created after this ISO8601 date
      in: query
      name: date_start
      required: false
      schema:
        type: string
    end_id_parameter:
      description: The ID to end returning events at
      example: 19
      in: query
      name: end_id
      required: false
      schema:
        type: string
    event_id_parameter:
      description: The ID of the event
      example: 9
      in: path
      name: event_id
      required: true
      schema:
        type: integer
    event_type_parameter:
      description: The type of event to search for. Does not currently support custom events
      example: text
      in: query
      name: event_type
      required: false
      schema:
        type: string
    member_id_parameter:
      description: The ID of the member
      example: MEM-e46d9542-752a-4786-8f12-25a2e623a793
      in: path
      name: member_id
      required: true
      schema:
        type: string
    order:
      description: Show the most (`desc`) / least (`asc`) recently created entries first
      in: query
      name: order
      required: false
      schema:
        default: asc
        enum:
          - asc
          - desc
        type: string
    page_size:
      description: The number of results returned per page.   The default value is `10`. The maximum value is `100`.
      in: query
      name: page_size
      required: false
      schema:
        default: 10
        maximum: 100
        type: integer
    start_id_parameter:
      description: The ID to start returning events at
      example: 13
      in: query
      name: start_id
      required: false
      schema:
        type: string
    user_id_parameter:
      description: The ID of the user
      example: USR-e46d9542-752a-4786-8f12-25a2e623a793
      in: path
      name: user_id
      required: true
      schema:
        type: string
  schemas:
    all_events:
      anyOf:
        - $ref: "#/components/schemas/text_event"
        - $ref: "#/components/schemas/custom_event"
        - $ref: "#/components/schemas/member_invited_event"
        - $ref: "#/components/schemas/member_left_event"
    conversation_display_name:
      description: The public facing name of the conversation
      example: Conversation with Ashley
      type: string
    conversation_id:
      description: Automatically generated conversation ID
      example: CON-c4724477-72ac-438e-9fc0-1d3e2ff8728c
      type: string
    conversation_image_url:
      description: An image URL that you associate with the conversation
      example: https://example.com/my-image.png
      type: string
    conversation_list:
      properties:
        _links:
          properties:
            self:
              properties:
                href:
                  example: https://api.nexmo.com/v0.2/conversations/CON-c4724477-72ac-438e-9fc0-1d3e2ff8728c
                  type: string
              type: object
          type: object
        display_name:
          $ref: "#/components/schemas/conversation_display_name"
        id:
          description: The ID of the conversation
          example: CON-afe887d8-d587-4280-9aae-dfa4c9227d5e
          type: string
        image_url:
          $ref: "#/components/schemas/conversation_image_url"
        name:
          $ref: "#/components/schemas/conversation_name"
        timestamp:
          properties:
            created:
              description: The time that the conversation was created
              example: 2019-09-03T18:40:24.324Z
              type: string
          type: object
      type: object
    conversation_name:
      description: Your internal conversation name. Must be unique
      example: my-conversation
      type: string
    custom_event:
      allOf:
        - description: Custom
          properties:
            body:
              description: The body of your `custom` event
              example:
                my: Custom Data
              type: object
            type:
              description: The event type (`custom:<YOUR_IDENTIFIER>`)
              example: custom:my_event
              type: string
          x-tab-id: custom-event
        - $ref: "#/components/schemas/event"
    event:
      properties:
        _links:
          properties:
            self:
              properties:
                href:
                  example: https://api.nexmo.com/v0.2/conversations/CON-92a44c64-7e4e-485f-a0c4-1f2adfc44625/events/9
                  type: string
              type: object
          type: object
        from:
          description: The member ID of the sender
          example: MEM-afe887d8-d587-4280-9aae-dfa4c9227d5e
          type: string
        id:
          description: The ID of the event
          example: 9
          type: integer
        timestamp:
          description: The time that the event happened
          example: 2019-09-12T19:49:21.823Z
          type: string
      type: object
    member:
      allOf:
        - $ref: "#/components/schemas/member_list"
        - properties:
            channel:
              properties:
                type:
                  description: The channel that the member joins with
                  enum:
                    - app
                  example: app
                  type: string
              type: object
            initiator:
              properties:
                invited:
                  properties:
                    is_system:
                      example: true
                      type: boolean
                  type: object
                joined:
                  properties:
                    is_system:
                      example: true
                      type: boolean
                  type: object
              type: object
            media:
              description: The current media state for the member
              properties:
                audio_settings:
                  description: The current audio state for the member
                  properties:
                    earmuffed:
                      description: Can the member hear other participants?
                      example: false
                      type: boolean
                    enabled:
                      description: Is audio enabled?
                      example: false
                      type: boolean
                    muted:
                      description: Can the member speak to other participants?
                      example: false
                      type: boolean
                  type: object
              type: object
            timestamp:
              properties:
                invited:
                  description: The time that an invitation was sent
                  example: 2019-09-03T18:40:24.324Z
                  type: string
                joined:
                  description: The time that the conversation was joined
                  example: 2019-09-12T16:27:07.450Z
                  type: string
                left:
                  description: The time that the member left the conversation
                  example: 2019-09-13T02:16:55.390Z
                  type: string
              type: object
          type: object
    member_invited_event:
      allOf:
        - description: Member Invited
          properties:
            type:
              description: The event type (`member:invited`)
              example: member:invited
              type: string
          x-tab-id: member-invited
        - $ref: "#/components/schemas/event"
        - properties:
            body:
              $ref: "#/components/schemas/member"
    member_left_event:
      allOf:
        - description: Member Left
          properties:
            type:
              description: The event type (`member:left`)
              example: member:left
              type: string
          x-tab-id: member-left
        - $ref: "#/components/schemas/event"
        - properties:
            body:
              $ref: "#/components/schemas/member"
    member_list:
      properties:
        _links:
          properties:
            self:
              properties:
                href:
                  example: https://api.nexmo.com/v0.2/conversations/CON-92a44c64-7e4e-485f-a0c4-1f2adfc44625/members/MEM-e784d5d1-dff2-424a-9de7-bc34f1901177
                  type: string
              type: object
          type: object
        display_name:
          description: The display name of the User
          example: Ashley Arthur
          type: string
        id:
          description: Member ID
          example: MEM-afe887d8-d587-4280-9aae-dfa4c9227d5e
          type: string
        name:
          description: The name of the User
          example: ashley
          type: string
        state:
          description: The state that the member is in for this conversation
          enum:
            - INVITED
            - JOINED
          example: JOINED
          type: string
        user_id:
          description: The ID of the User
          example: USR-2c52f0ec-7a48-4b52-9d47-df47482b2b7e
          type: string
      type: object
    text_event:
      allOf:
        - description: Text
          properties:
            body:
              description: The body of the `text` event
              properties:
                text:
                  description: The text sent in this event
                  example: Hello World
                  type: string
              type: object
            conversation_id:
              description: The ID of the Conversation that the member belongs to
              example: CON-92a44c64-7e4e-485f-a0c4-1f2adfc44625
              type: string
            type:
              description: The event type (`text`)
              example: text
              type: string
          x-tab-id: text-event
        - $ref: "#/components/schemas/event"
    user_id:
      description: The ID of the user
      example: USR-e46d9542-752a-4786-8f12-25a2e623a793
      type: string
    user_links:
      properties:
        self:
          properties:
            href:
              example: https://api.nexmo.com/v0.2/users/USR-e46d9542-752a-4786-8f12-25a2e623a793
              type: string
          type: object
      type: object
    user_list:
      properties:
        _links:
          $ref: "#/components/schemas/user_links"
        id:
          $ref: "#/components/schemas/user_id"
        name:
          $ref: "#/components/schemas/user_name"
      type: object
    user_name:
      description: The name of the user
      example: ashley
      type: string
