openapi: 3.0.0
servers:
  - url: 'https://api.nexmo.com/beta'
info:
  version: 1.7.5
  title: Nexmo Conversation API
  description: 'The Nexmo 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.'
  contact:
    name: Nexmo DevRel
    email: devrel@nexmo.com
    url: 'https://developer.nexmo.com/'
  x-label: Developer Preview
paths:
  /conversations:
    post:
      operationId: createConversation
      tags:
        - conversation
      summary: Create a conversation
      responses:
        '200':
          $ref: '#/components/responses/ConversationLite'
      requestBody:
        $ref: '#/components/requestBodies/Conversation'
    get:
      operationId: listConversations
      tags:
        - conversation
      summary: List conversations
      description: >
          <div class="Vlt-callout Vlt-callout--warning">
          <i></i>
          <div class="Vlt-callout__content">
          <p><strong>This API endpoint is deprecated. Please use <a href="/api/conversation.v2#get-conversations">/beta2/conversations</a></strong>.<br />This endpoint will return a maximum of 100 items.</p>
          </div>
          </div>

          List all conversations associated with your application. 
          This endpoint required an admin JWT. To find all conversations for
          the currently logged in user, see [GET /users/:id/conversations](#getuserConversations)
      parameters:
        - $ref: '#/components/parameters/date_start'
        - $ref: '#/components/parameters/date_end'
        - $ref: '#/components/parameters/page_size'
        - $ref: '#/components/parameters/record_index'
        - $ref: '#/components/parameters/order'
      responses:
        '200':
          description: List Conversations Response Payload Object.
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: number
                    example: '100'
                    description: The total number of records returned by your request.
                  page_size:
                    $ref: '#/components/schemas/page_size'
                  record_index:
                    $ref: '#/components/schemas/record_index'
                  _links:
                    $ref: '#/components/schemas/_links_conversations_list'
                  _embedded:
                    description: 'A list of conversation objects. See the [get details of a specific conversation](#retrieveConversation) response fields for a description of the nested objects'
                    type: object
                    properties:
                      conversations:
                        type: array
                        items:
                          type: object
                          properties:
                            uuid:
                              $ref: '#/components/schemas/conversation_id'
                            name:
                              $ref: '#/components/schemas/name_conversation'
                            href:
                              $ref: '#/components/schemas/href_conversation'
                          required:
                            - uuid
                            - name
                            - href
                    required:
                      - conversations
                required:
                  - count
                  - page_size
                  - record_index
                  - _links
                  - _embedded
  '/conversations/{conversation_id}':
    parameters:
      - $ref: '#/components/parameters/conversation_id'
    put:
      operationId: replaceConversation
      tags:
        - conversation
      summary: Update a conversation
      responses:
        '200':
          $ref: '#/components/responses/ConversationLite'
      requestBody:
        $ref: '#/components/requestBodies/Conversation'
    get:
      operationId: retrieveConversation
      tags:
        - conversation
      summary: Retrieve a conversation
      responses:
        '200':
          description: Retrieve a conversation
          content:
            application/json:
              schema:
                type: object
                description: Conversation Object
                properties:
                  uuid:
                    $ref: '#/components/schemas/conversation_id'
                  name:
                    $ref: '#/components/schemas/name_conversation'
                  numbers:
                    type: object
                    properties: {}
                  properties:
                    type: object
                    properties:
                      video:
                        type: boolean
                        example: false
                  display_name:
                    $ref: '#/components/schemas/display_name'
                  timestamp:
                    $ref: '#/components/schemas/timestamp_res_conversation'
                  sequence_number:
                    type: string
                    example: '1'
                    description: 'The last Event ID in this conversation. This ID can be used to [retrieve a specific event](#getEvent)'
                  members:
                    type: array
                    description: Users associated to this conversation as members
                    items:
                      type: object
                      properties:
                        member_id:
                          $ref: '#/components/schemas/member_id'
                        user_id:
                          $ref: '#/components/schemas/user_id'
                        name:
                          $ref: '#/components/schemas/name_user'
                        state:
                          $ref: '#/components/schemas/member_state'
                        timestamp:
                          $ref: '#/components/schemas/timestamp_res_member'
                        initiator:
                          $ref: '#/components/schemas/initiator'
                        channel:
                          $ref: '#/components/schemas/channel'
                  api_key:
                    type: string
                    description: The API key for your account
                  _links:
                    $ref: '#/components/schemas/_links_conversation'
                required:
                  - uuid
    delete:
      operationId: deleteConversation
      tags:
        - conversation
      summary: Delete a conversation
      responses:
        '200':
          $ref: '#/components/responses/SuccessEmptyJSON'
  '/conversations/{conversation_id}/record':
    servers:
      - url: 'https://api.nexmo.com/v1'
        description: Override base path for the PUT /conversations/{conversation_id}/record operation
    parameters:
      - $ref: '#/components/parameters/conversation_id'
    put:
      operationId: recordConversation
      tags:
        - conversation
      summary: Record a conversation
      responses:
        '204':
          description: 'No Content'
        '404':
          description: 'Not Found'
        '400':
          description: 'Bad Request'
      requestBody:
        $ref: '#/components/requestBodies/RecordConversation'
  '/conversations/{conversation_id}/events':
    parameters:
      - $ref: '#/components/parameters/conversation_id'
    post:
      operationId: createEvent
      tags:
        - event
      summary: Create an event
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: Create New Event Request Payload Object
              properties:
                type:
                  $ref: '#/components/schemas/event_type'
                to:
                  $ref: '#/components/schemas/member_id'
                from:
                  $ref: '#/components/schemas/member_id'
                body:
                  $ref: '#/components/schemas/event_body'
              required:
                - type
                - from
      responses:
        '201':
          description: Create New Event Response Payload Object
          content:
            application/json:
              schema:
                type: object
                description: Create New Event Response Payload Object
                properties:
                  id:
                    $ref: '#/components/schemas/event_id'
                  timestamp:
                    $ref: '#/components/schemas/timestamp_res_event'
                  href:
                    $ref: '#/components/schemas/href_event'
    get:
      operationId: getEvents
      description: >
          <div class="Vlt-callout Vlt-callout--warning">
          <i></i>
          <div class="Vlt-callout__content">
          <p><strong>This API endpoint is deprecated. Please use <a href="/api/conversation.v2#get-events">/beta2/events</a></strong><br />This endpoint will return a maximum of 100 items.</p>
          </div>
          </div>

      tags:
        - event
      summary: List events
      responses:
        '200':
          description: Retrieve Events Response Payload Object
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/event_retrieved'
  '/conversations/{conversation_id}/events/{event_id}':
    parameters:
      - $ref: '#/components/parameters/conversation_id'
      - $ref: '#/components/parameters/event_id'
    get:
      operationId: getEvent
      tags:
        - event
      summary: Retrieve an event
      responses:
        '200':
          description: Retrieve an event Content Payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/event_retrieved'
    delete:
      operationId: deleteEvent
      tags:
        - event
      summary: Delete an event
      responses:
        '200':
          $ref: '#/components/responses/SuccessEmptyJSON'
  '/conversations/{conversation_id}/members':
    parameters:
      - $ref: '#/components/parameters/conversation_id'
    get:
      operationId: getMembers
      description: >
          <div class="Vlt-callout Vlt-callout--warning">
          <i></i>
          <div class="Vlt-callout__content">
          <p><strong>This API endpoint is deprecated. Please use <a href="/api/conversation.v2#get-members">/beta2/members</a></strong><br />This endpoint will return a maximum of 100 items.</p>
          </div>
          </div>
      tags:
        - member
      summary: List members
      responses:
        '200':
          description: Members List Object
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    user_id:
                      $ref: '#/components/schemas/user_id'
                    user_name:
                      $ref: '#/components/schemas/name_user'
                    name:
                      $ref: '#/components/schemas/name_user'
                    state:
                      $ref: '#/components/schemas/member_state'
                  required:
                    - user_id
                    - name
                    - user_name
                    - state
    post:
      operationId: createMember
      tags:
        - member
      summary: Create a member
      responses:
        '201':
          description: 'Create or invite Member in invite state '
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    $ref: '#/components/schemas/member_id'
                  user_id:
                    $ref: '#/components/schemas/user_id'
                  state:
                    $ref: '#/components/schemas/member_state'
                  timestamp:
                    $ref: '#/components/schemas/timestamp_res_member'
                  channel:
                    $ref: '#/components/schemas/channel'
                  href:
                    $ref: '#/components/schemas/href_member'
                  initiator:
                    $ref: '#/components/schemas/initiator'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: 'Create a Member in invite state '
              required:
                - user_id
                - channel
              properties:
                action:
                  $ref: '#/components/schemas/member_action'
                user_id:
                  $ref: '#/components/schemas/user_id'
                member_id:
                  $ref: '#/components/schemas/member_id'
                channel:
                  $ref: '#/components/schemas/channel'
                media:
                  $ref: '#/components/schemas/media'
                knocking_id:
                  $ref: '#/components/schemas/knocker_id'
                member_id_inviting:
                  $ref: '#/components/schemas/member_id_inviting'
  '/conversations/{conversation_id}/members/{member_id}':
    parameters:
      - $ref: '#/components/parameters/conversation_id'
      - $ref: '#/components/parameters/member_id'
    get:
      operationId: getMember
      tags:
        - member
      summary: Retrieve a member
      responses:
        '200':
          description: Retrieve member payload
          content:
            application/json:
              schema:
                properties:
                  id:
                    $ref: '#/components/schemas/member_id'
                  href:
                    $ref: '#/components/schemas/href_member'
    put:
      operationId: updateMember
      tags:
        - member
      summary: Update a member
      responses:
        '200':
          description: Member retrieved
          content:
            application/json:
              schema:
                properties:
                  id:
                    $ref: '#/components/schemas/member_id'
                  href:
                    $ref: '#/components/schemas/href_member'
      requestBody:
        content:
          application/json:
            schema:
              properties:
                action:
                  $ref: '#/components/schemas/member_action'
                channel:
                  $ref: '#/components/schemas/channel'
    delete:
      operationId: deleteMember
      tags:
        - member
      summary: Delete a member
      responses:
        '200':
          $ref: '#/components/responses/SuccessEmptyJSON'
  /users:
    get:
      operationId: getUsers
      description: >
          <div class="Vlt-callout Vlt-callout--warning">
          <i></i>
          <div class="Vlt-callout__content">
          <strong>This API endpoint is deprecated. Please use <a href="/api/conversation.v2#get-users">/beta2/users</a><br />This endpoint will return a maximum of 100 items.</strong>
          </div>
          </div>
      tags:
        - user
      summary: List users
      responses:
        '200':
          description: List of users
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      $ref: '#/components/schemas/user_id'
                    name:
                      $ref: '#/components/schemas/name_user'
                    href:
                      $ref: '#/components/schemas/href_user'
    post:
      operationId: createUser
      tags:
        - user
      summary: Create a user
      description: 'Note: Users must be created with an admin JWT.'
      responses:
        '200':
          description: Create a user response
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    $ref: '#/components/schemas/name_user'
                  display_name:
                    $ref: '#/components/schemas/display_name_user'
                  href:
                    $ref: '#/components/schemas/href_user'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: 'Create a Member in invite state '
              properties:
                name:
                  $ref: '#/components/schemas/name_user'
                display_name:
                  $ref: '#/components/schemas/display_name_user'
                image_url:
                  $ref: '#/components/schemas/image_url'
  '/users/{user_id}':
    parameters:
      - $ref: '#/components/parameters/user_id'
    get:
      operationId: getUser
      tags:
        - user
      summary: Retrieve a user
      responses:
        '200':
          description: Retrieve a user
          content:
            application/json:
              schema:
                properties:
                  id:
                    $ref: '#/components/schemas/user_id'
                  name:
                    $ref: '#/components/schemas/name_user'
                  href:
                    type: string
                    example: 'https://api.nexmo.com/beta/users/USR-63f61863-4a51-4f6b-86e1-46edebio0391'
    put:
      operationId: updateUser
      tags:
        - user
      summary: Update a user
      responses:
        '200':
          description: Retrieve a user
          content:
            application/json:
              schema:
                properties:
                  id:
                    $ref: '#/components/schemas/user_id'
                  href:
                    $ref: '#/components/schemas/href_user'
      requestBody:
        content:
          application/json:
            schema:
              properties:
                name:
                  $ref: '#/components/schemas/name_user'
                display_name:
                  $ref: '#/components/schemas/display_name_user'
                image_url:
                  $ref: '#/components/schemas/image_url'
                channels:
                  $ref: '#/components/schemas/channel'
    delete:
      operationId: deleteUser
      tags:
        - user
      summary: Delete a user
      responses:
        '200':
          $ref: '#/components/responses/SuccessEmptyJSON'
  '/users/{user_id}/conversations':
    parameters:
      - $ref: '#/components/parameters/user_id'
    get:
      operationId: getuserConversations
      tags:
        - user
      summary: List user conversations
      responses:
        '200':
          description: List user conversations
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      $ref: '#/components/schemas/name_conversation'
                    image_url:
                      $ref: '#/components/schemas/image_url'
                    display_name:
                      $ref: '#/components/schemas/display_name'
                    state:
                      $ref: '#/components/schemas/member_state'
                    member_id:
                      $ref: '#/components/schemas/member_id'
                    sequence_number:
                      type: integer
                      format: url
                      description: the id of the last event of the conversation (event's id is an incremental number
                      example: '123'
                    href:
                      $ref: '#/components/schemas/href'
                    id:
                      $ref: '#/components/schemas/conversation_id'
                    timestamp:
                      type: object
                      properties:
                        created:
                          $ref: '#/components/schemas/timestamp'
  /legs:
    get:
      operationId: listLegs
      tags:
        - leg
      summary: List legs
      responses:
        '200':
          description: List Legs Successfully
          content:
            application/json:
              schema:
                type: object
                description: List Legs Response Payload Object
                properties:
                  count:
                    type: number
                    example: '100'
                    description: The total number of records returned by your request.
                  page_size:
                    $ref: '#/components/schemas/page_size'
                  record_index:
                    $ref: '#/components/schemas/record_index'
                  _links:
                    type: object
                    properties:
                      self:
                        type: object
                        properties:
                          href:
                            type: string
                        required:
                          - href
                    required:
                      - self
                  _embedded:
                    description: 'A list of conversation objects. See the [get details of a specific conversation](#retrieveConversation) response fields for a description of the nested objects'
                    type: object
                    properties:
                      legs:
                        type: array
                        items:
                          type: object
                          properties:
                            uuid:
                              $ref: '#/components/schemas/leg_id'
                            type:
                              $ref: '#/components/schemas/channel_type'
                            conversation_uuid:
                              $ref: '#/components/schemas/conversation_id'
                            state:
                              $ref: '#/components/schemas/leg_state'
                            from:
                              type: object
                            to:
                              type: object
                            start_time:
                              $ref: '#/components/schemas/timestamp_leg_start_time'
                            start_end:
                              $ref: '#/components/schemas/timestamp_leg_end_time'
                            _links:
                              type: object
                            _embedded:
                              type: object
                          required:
                            - uuid
                            - name
                            - href
                    required:
                      - legs
                required:
                  - count
                  - page_size
                  - record_index
                  - _links
                  - _embedded
                example:
                  count: 1
                  page_size: 10
                  record_index: 0
                  _links:
                    self:
                      href: 'https://api.nexmo.com/beta/legs'
                  _embedded:
                    legs:
                      - uuid: 2a71f8a1-b6f1-42b3-9eef-c69729e17513
                        type: app
                        conversation_uuid: CON-511d076b-9d39-498c-baa7-b7a4bfbd6e32
                        status: completed
                        from:
                          type: app
                        to:
                          type: app
                        start_time: ''
                        end_time: ''
                        rtc:
                          session_id: SES-84ebef0d-321a-47e6-8446-f4fcc5ca74b9
                          state: terminated
                        _links:
                          self:
                            href: 'https://api.nexmo.com/beta/legs/2a71f8a1-b6f1-42b3-9eef-c69729e17513'
  '/legs/{leg_id}':
    parameters:
      - $ref: '#/components/parameters/leg_id'
    delete:
      operationId: deleteLeg
      tags:
        - leg
      summary: Delete a leg
      responses:
        '200':
          $ref: '#/components/responses/SuccessEmptyJSON'
components:
  schemas:
    initiator:
      type: object
      properties:
        joined:
          type: object
          properties:
            isSystem:
              type: boolean
              description: '`true` if the user was invited by an admin JWT. `user_id` and `member_id` will not exist if `true`'
            user_id:
                $ref: '#/components/schemas/user_id'
            member_id:
                $ref: '#/components/schemas/member_id'
 
    action:
      type: string
      example: start
      description: Recording Action
      enum:
        - start
        - stop
    event_url:
      type: array
      items: 
        type: string
        format: url
      example: '["https://example.com/event"]'
      x-nexmo-developer-collection-description-shown: true
      description: The webhook endpoint where recording progress events are sent to.
    event_method:
      type: string
      description: The HTTP method used to send event information to event_url.
      example: POST
      default: POST
    split:
      type: string
      description: Record the sent and received audio in separate channels of a stereo recording
      example: conversation
      default: conversation
    format:
      type: string
      description: Record the Conversation in a specific format.
      example: mp3
      default: mp3
      enum:
        - mp3
        - wav
    leg_state:
      type: string
      example: terminated
      description: Leg Status
      enum:
        - terminated
    conversation_id:
      type: string
      example: CON-63f61863-4a51-4f6b-86e1-46edebio0391
      description: The unique identifier for this conversation
    member_id:
      type: string
      example: MEM-63f61863-4a51-4f6b-86e1-46edebio0391
      description: Member ID
    member_id_inviting:
      type: string
      example: MEM-63f61863-4a51-4f6b-86e1-46edebio0391
      description: Member ID of the member that sends the invitation
    member_action:
      type: string
      description: Invite or join a member to a conversation
      example: join
      enum:
        - invite
        - join
    user_id_or_user_name:
      type: string
      description: user name or user id of the inviter
      example: someone_else_user_name
    user_id:
      type: string
      example: USR-63f61863-4a51-4f6b-86e1-46edebio0391
      description: User ID
    name:
      type: string
      example: my_unique_name
      description: Unique name
    name_conversation:
      type: string
      example: customer_chat
      description: Unique name for a conversation
    name_user:
      type: string
      example: my_user_name
      description: Unique name for a user
    href:
      type: string
      format: url
      example: 'https://api.nexmo.com/beta/converations/CON-63f61863-4a51-4f6b-86e1-46edebio0391'
      description: A link towards a resources included in Conversation API
    href_conversation:
      type: string
      format: url
      example: 'https://api.nexmo.com/beta/converations/CON-63f61863-4a51-4f6b-86e1-46edebio0391'
      description: A link towards a conversation included in Conversation API
    href_conversations_list:
      type: string
      format: url
      example: 'https://api.nexmo.com/beta/converations?page_size=2&record_index=10&'
      description: A link towards a conversations list included in Conversation API
    href_member:
      type: string
      format: url
      example: 'https://api.nexmo.com/beta/converations/CON-63f61863-4a51-4f6b-86e1-46edebio0391/members/MEM-63f61863-4a51-4f6b-86e1-46edebio0391'
      description: A link towards a member included in Conversation API
    href_user:
      type: string
      format: url
      example: 'https://api.nexmo.com/beta/converations/USR-63f61863-4a51-4f6b-86e1-46edebio0391'
      description: A link towards a user included in Conversation API
    href_event:
      type: string
      format: url
      example: 'https://api.nexmo.com/beta/converations/CON-63f61863-4a51-4f6b-86e1-46edebio0391/events/1'
      description: A link towards a conversation event included in Conversation API
    href_rtc:
      type: string
      format: url
      example: 'https://api.nexmo.com/beta/converations/CON-63f61863-4a51-4f6b-86e1-46edebio0391/rtc/7777777777777'
      description: A link towards a rtc (leg) included in Conversation API
    event_id:
      type: string
      example: '5'
      description: Event id. This is a progressive integer
    image_url:
      type: string
      format: url
      example: 'https://example.com/image.png'
      description: A link to an image for conversations' and users' avatars
    display_name:
      type: string
      example: Customer Chat
      description: The display name for the conversation. It does not have to be unique
    display_name_user:
      type: string
      example: My User Name
      description: A string to be displayed as user name. It does not need to be unique
    numbers:
      type: object
      description: 'An object containing number on different channels. '
      example:
        pstn: 14155550100
        sms: 442079460000
      properties:
        sms:
          type: string
          description: phone number used for sms channel
          example: 442079460000
        pstn:
          type: string
          description: phone number used for pstn channel
          example: 14155550100
    conversation_properties:
      type: object
      description: Conversation properties
      properties:
        ttl:
          type: number
          example: 60
          description: 'Time to leave. After how many seconds an empty conversation is deleted.'
    _links_conversations_list:
      type: object
      description: 'A series of links between resources in this API in the http://stateless.co/hal_specification.html.'
      properties:
        self:
          type: object
          properties:
            href:
              $ref: '#/components/schemas/href_conversations_list'
          required:
            - href
      required:
        - self
    _links_conversation:
      type: object
      properties:
        self:
          type: object
          properties:
            href:
              $ref: '#/components/schemas/href_conversation'
    page_size:
      type: number
      description: The amount of records returned in this response
      minimum: 1
      maximum: 100
      default: 10
    record_index:
      type: number
      description: 'Return `page_size` amount of conversations from this index in the response. That is, if your request returns 300 conversations, set `record_index` to 5 in order to return conversations 50 to 59. The default value is 0. That is, the first `page_size` calls.'
      default: 0
      minimum: 0
    timestamp:
      type: string
      example: '2020-01-01T14:00:00.00Z'
      description: Timestamp
    timestamp_created:
      type: string
      example: '2020-01-01T14:00:00.00Z'
      description: Time of creation
    timestamp_updated:
      type: string
      example: '2020-01-01T14:05:00.00Z'
      description: Time of last update
    timestamp_destroyed:
      type: string
      example: '2020-01-01T14:20:00.00Z'
      description: Time of last update
    timestamp_leg_start_time:
      type: string
      example: '2020-01-01T14:00:00.00Z'
      description: Time of leg start
    timestamp_leg_end_time:
      type: string
      example: '2020-01-01T14:00:00.00Z'
      description: Time of leg end
    timestamp_res_event:
      type: string
      example: '2020-01-01T14:00:00.00Z'
      description: Time of event creation
    timestamp_res_conversation:
      type: object
      properties:
        created:
          $ref: '#/components/schemas/timestamp_created'
        updated:
          $ref: '#/components/schemas/timestamp_updated'
        destroyed:
          $ref: '#/components/schemas/timestamp_destroyed'
    timestamp_res_member:
      type: object
      properties:
        invited:
          $ref: '#/components/schemas/timestamp'
        joined:
          $ref: '#/components/schemas/timestamp'
        left:
          $ref: '#/components/schemas/timestamp'
    timestamp_obj_leg:
      type: object
      properties:
        start:
          $ref: '#/components/schemas/timestamp_created'
        end:
          $ref: '#/components/schemas/timestamp'
        request:
          $ref: '#/components/schemas/timestamp'
    member_state:
      type: string
      description: 'The state that the member is in. Possible values are `invited`, `joined`, `left`, or `unknown`'
      example: invited
      enum:
        - invited
        - joined
        - left
        - unknown
    leg_id:
      type: string
      example: a595959595959595995
      description: The id of the leg. rtc_id and call_id are leg id
    channel_number:
      type: string
      example: a447700900585
      description: this can be a phone number or a random string
    channel_type:
      type: string
      example: phone
      description: Channel type
      enum:
        - app
        - phone
        - sip
        - websocket
        - vbc
    channel:
      type: object
      description: 'A user who joins a conversation as a member can have one channel per membership type. Channels can be `app`, `phone`, `sip`, `websocket`, or `vbc`'
      properties:
        type:
          $ref: '#/components/schemas/channel_type'
        leg_id:
          $ref: '#/components/schemas/leg_id'
        from:
          oneOf:
            - "$ref": "voice.yml#/components/schemas/EndpointApp"
            - "$ref": "voice.yml#/components/schemas/EndpointPhone"
            - "$ref": "voice.yml#/components/schemas/EndpointSip"
            - "$ref": "voice.yml#/components/schemas/EndpointWebsocket"
            - "$ref": "voice.yml#/components/schemas/EndpointVBCExtension"
        to:
          oneOf:
            - "$ref": "voice.yml#/components/schemas/EndpointApp"
            - "$ref": "voice.yml#/components/schemas/EndpointPhone"
            - "$ref": "voice.yml#/components/schemas/EndpointSip"
            - "$ref": "voice.yml#/components/schemas/EndpointWebsocket"
            - "$ref": "voice.yml#/components/schemas/EndpointVBCExtension"
        leg_ids:
          type: array
          description: Leg ids associated with this Channel. The first item in the array represents the main active Leg. The second item, if exists, represents a screen-share Leg.
          items:
            properties:
              leg_id:
                $ref: '#/components/schemas/leg_id'
    media:
      type: object
      description: Media Object
      properties: {}
      example:
        audio_settings:
          enabled: false
          earmuffed: false
          muted: false
    event_type:
      type: string
      description: Event type
      example: text
    event_body:
      type: object
      description: Event Body
      example:
        text: My Text
    event_retrieved:
      type: object
      description: Retrieve Events Response Payload Object Item
      properties:
        id:
          $ref: '#/components/schemas/event_id'
        type:
          $ref: '#/components/schemas/event_type'
        from:
          $ref: '#/components/schemas/member_id'
        to:
          $ref: '#/components/schemas/member_id'
        body:
          $ref: '#/components/schemas/event_body'
        state:
          $ref: '#/components/schemas/member_state'
        timestamp:
          $ref: '#/components/schemas/timestamp_created'
        href:
          $ref: '#/components/schemas/href_event'
      required:
        - id
        - type
        - body
        - timestamp
        - href
    knocker_id:
      type: string
      description: Knocker ID. A knocker is a pre-member of a conversation who does not exist yet
      example: a972836a-450f-35fa-156c-52a2ab5b7d25
  parameters:
    leg_id:
      name: leg_id
      in: path
      required: true
      description: Leg ID
      schema:
        type: string
    user_id:
      name: user_id
      in: path
      required: true
      description: User ID
      schema:
        type: string
    conversation_id:
      name: conversation_id
      in: path
      required: true
      description: Conversation ID
      example: CON-f972836a-550f-45fa-956c-12a2ab5b7d22
      schema:
        type: string
    member_id:
      name: member_id
      in: path
      required: true
      description: Member ID
      schema:
        type: string
    event_id:
      name: event_id
      in: path
      description: Event ID
      required: true
      schema:
        type: string
    date_start:
      name: date_start
      in: query
      required: false
      description: Return the records that occurred after this point in time.
      schema:
        example: '2018-01-01 10:00:00'
        type: string
        format: dateTime
    date_end:
      name: date_end
      in: query
      required: false
      description: Return the records that occurred before this point in time.
      schema:
        example: '2018-01-01 12:00:00'
        type: string
        format: dateTime
    page_size:
      name: page_size
      in: query
      description: Return this amount of records in the response
      required: false
      schema:
        $ref: '#/components/schemas/page_size'
    record_index:
      name: record_index
      in: query
      description: Return calls from this index in the response
      required: false
      schema:
        $ref: '#/components/schemas/record_index'
    order:
      name: order
      in: query
      description: Return the records in ascending or descending order.
      required: false
      schema:
        type: string
        default: asc
        enum:
          - asc
          - desc
          - ASC
          - DESC
  responses:
    ConversationLite:
      description: Create / Update Conversation Response Payload Object
      content:
        application/json:
          schema:
            type: object
            properties:
              id:
                $ref: '#/components/schemas/conversation_id'
              href:
                $ref: '#/components/schemas/href_conversation'
            required:
              - id
              - href
    SuccessEmptyJSON:
      description: Success response with empty JSON
      content:
        application/json:
          schema:
            type: object
            description: Empty JSON payload
            example: {}
  requestBodies:
    EmptyBody:
      description: Conversation Request Payload Object
      required: true
      content:
        application/json:
          schema:
            type: object
            example: {}
    Conversation:
      description: Conversation Request Payload Object
      content:
        application/json:
          schema:
            type: object
            properties:
              name:
                $ref: '#/components/schemas/name_conversation'
              display_name:
                $ref: '#/components/schemas/display_name'
              image_url:
                $ref: '#/components/schemas/image_url'
              numbers:
                $ref: '#/components/schemas/numbers'
              properties:
                $ref: '#/components/schemas/conversation_properties'
    RecordConversation:
      description: Record Conversation Request Payload Object
      content:
        application/json:
          schema:
            type: object
            properties:
              action:
                $ref: '#/components/schemas/action'
              event_url:
                $ref: '#/components/schemas/event_url'
              event_method:
                $ref: '#/components/schemas/event_method'
              split:
                $ref: '#/components/schemas/split'
              format:
                $ref: '#/components/schemas/format'
            required:
              - action
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
security:
  - bearerAuth: []

tags:
  - name: conversation
    description: A conversation is a shared core component that Nexmo APIs rely on. Conversations happen over multiple mediums and and can have associated Users through Memberships.
  - name: user
    description: 'The concept of a user exists in Nexmo APIs, you can associate one with a user in your own application if you choose. A user can have multiple memberships to conversations and can communicate with other users through various different mediums.'
  - name: member
    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: event
    description: 'Events are actions that occur within a conversation. Examples of this includes: Text events from members, or invite events from users'
  - name: leg
    description: 'A leg can be a video call, IP call, or PSTN call that users participate in using multiple platforms. With this endpoint you can retrieve the details about all of the legs that took place in your application.'
  - name: rtc
    description: Rtc actions. Any rtc action related (like starting a new rtc connection).
