Nexmo Stitch API Developer Preview

The Nexmo Stitch 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.

Download OpenAPI 3 Definition

Conversation

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.

  • Key
    Description
  • uuid
    Required | string

    Conversation ID

  • name
    string

    Conversation Name

  • display_name
    string

    The display name of the conversation

  • timestamp
    string

    time when conversation was created

  • sequence_number
    string

    the last event id

  • members
    array
    of object's
  • api_key
    string

    None

  • _links
    object
    • Key
      Description
    • self
      object
      • Key
        Description
      • href
        string

        None

  • _embedded
    object
    • Key
      Description
    • legs
      object
      • Key
        Description
      • _links
        array
        of object's

Example Model

{
  "uuid": "63f61863-4a51-4f6b-86e1-46edebio0391",
  "name": "nexmo-conference-standard",
  "display_name": "My-Conversation",
  "timestamp": "2020-01-01T14:00:00.00Z",
  "sequence_number": "1",
  "members": [
    {
      "member_id": "abc123",
      "user_id": "abc123",
      "name": "abc123",
      "state": "abc123",
      "timestamp": "abc123",
      "invited_by": "abc123"
    }
  ],
  "api_key": "abc123",
  "_links": {
    "self": {
      "href": "abc123"
    }
  },
  "_embedded": {
    "legs": {
      "_links": [
        {
          "leg_id": "abc123",
          "member_id": "abc123"
        }
      ]
    }
  }
}

Create a conversation

POST https://api.nexmo.com/beta /conversations

Request body application/json

  • Key
    Description
    Example
    Default
  • name
    string

    Unique name (within the same application) for the conversation. If not provided, one will be automatically generated.

    nexmo-conference-standard
    63f61863-4a51-4f6b-86e1-46edebio0391
  • display_name
    Required | string

    The display name of the conversation

    My-Conversation
    None

View response field descriptions


201 HTTP response

{
  "id": "63f61863-4a51-4f6b-86e1-46edebio0391",
  "href": "abc123"
}

400 HTTP response

List conversations

GET https://api.nexmo.com/beta /conversations

View response field descriptions


200 HTTP response

{
  "count": "100",
  "page_size": "20",
  "record_index": 1,
  "_links": {
    "self": {
      "href": "abc123"
    }
  },
  "_embedded": {
    "conversations": [
      {
        "uuid": "abc123",
        "name": "abc123",
        "href": "abc123"
      }
    ]
  }
}

400 HTTP response

Update a conversation

PUT https://api.nexmo.com/beta /conversations/:conv_id

Path Parameters

  • Key
    Description
    Example
    Default
  • conv_id
    Required | string

    Conversation ID

    None
    None

Request body application/json

  • Key
    Description
    Example
    Default
  • name
    string

    Unique name (within the same application) for the conversation. If not provided, one will be automatically generated.

    nexmo-conference-standard
    63f61863-4a51-4f6b-86e1-46edebio0391
  • display_name
    string

    The display name of the conversation

    My-Conversation
    None

View response field descriptions


200 HTTP response

{
  "id": "63f61863-4a51-4f6b-86e1-46edebio0391",
  "href": "abc123"
}

400 HTTP response

Retrieve a conversation

GET https://api.nexmo.com/beta /conversations/:conv_id

Path Parameters

  • Key
    Description
    Example
    Default
  • conv_id
    Required | string

    Conversation ID

    None
    None

View response field descriptions


200 HTTP response

{
  "uuid": "63f61863-4a51-4f6b-86e1-46edebio0391",
  "name": "nexmo-conference-standard",
  "display_name": "My-Conversation",
  "timestamp": "2020-01-01T14:00:00.00Z",
  "sequence_number": "1",
  "members": [
    {
      "member_id": "abc123",
      "user_id": "abc123",
      "name": "abc123",
      "state": "abc123",
      "timestamp": "abc123",
      "invited_by": "abc123"
    }
  ],
  "api_key": "abc123",
  "_links": {
    "self": {
      "href": "abc123"
    }
  },
  "_embedded": {
    "legs": {
      "_links": [
        {
          "leg_id": "abc123",
          "member_id": "abc123"
        }
      ]
    }
  }
}

400 HTTP response

Delete a conversation

DELETE https://api.nexmo.com/beta /conversations/:conv_id

Path Parameters

  • Key
    Description
    Example
    Default
  • conv_id
    Required | string

    Conversation ID

    None
    None

View response field descriptions


200 HTTP response

{}

400 HTTP response

User

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.

  • Key
    Description
  • id
    Required | string

    None

  • href
    Required | string

    None

Example Model

{
  "id": "abc123",
  "href": "abc123"
}

Create a user

POST https://api.nexmo.com/beta /users

Request body application/json

  • Key
    Description
    Example
    Default
  • name
    string

    None

    None
    None
  • image_url
    string

    None

    None
    None
  • display_name
    string

    None

    None
    None
  • channels
    string

    None

    None
    None

View response field descriptions


201 HTTP response

{
  "id": "abc123",
  "href": "abc123"
}

400 HTTP response

List users

GET https://api.nexmo.com/beta /users

View response field descriptions


200 HTTP response

[
  {
    "id": "abc123",
    "href": "abc123"
  }
]

Retrieve a user

GET https://api.nexmo.com/beta /users/:user_id

Path Parameters

  • Key
    Description
    Example
    Default
  • user_id
    Required | string

    User ID

    None
    None

View response field descriptions


200 HTTP response

{
  "id": "abc123",
  "href": "abc123"
}

404 HTTP response

Update a user

PUT https://api.nexmo.com/beta /users/:user_id

Path Parameters

  • Key
    Description
    Example
    Default
  • user_id
    Required | string

    User ID

    None
    None

Request body application/json

  • Key
    Description
    Example
    Default
  • name
    string

    None

    None
    None
  • image_url
    string

    None

    None
    None
  • display_name
    string

    None

    None
    None
  • channels
    string

    None

    None
    None

View response field descriptions


200 HTTP response

{
  "id": "abc123",
  "href": "abc123"
}

404 HTTP response

Delete a user

DELETE https://api.nexmo.com/beta /users/:user_id

Path Parameters

  • Key
    Description
    Example
    Default
  • user_id
    Required | string

    User ID

    None
    None

View response field descriptions


200 HTTP response

{}

List user conversations

GET https://api.nexmo.com/beta /users/:user_id/conversations

Path Parameters

  • Key
    Description
    Example
    Default
  • user_id
    Required | string

    User ID

    None
    None

View response field descriptions


200 HTTP response

[
  {
    "id": "abc123",
    "href": "abc123"
  }
]

Member

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.

  • Key
    Description
  • id
    Required | string

    Member ID

  • user_id
    Required | string

    None

  • state
    Required | string

    None

  • timestamp
    Required | string

    None

  • channel
    Required | string

    None

  • href
    Required | string (url)

    None

Example Model

{
  "id": "abc123",
  "user_id": "abc123",
  "state": "abc123",
  "timestamp": "abc123",
  "channel": "abc123",
  "href": "abc123"
}

List members

GET https://api.nexmo.com/beta /conversations/:conv_id/members

Path Parameters

  • Key
    Description
    Example
    Default
  • conv_id
    Required | string

    Conversation ID

    None
    None

View response field descriptions


200 HTTP response

[
  {
    "user_id": "abc123",
    "user_name": "abc123",
    "name": "abc123",
    "state": "abc123"
  }
]

400 HTTP response

Create a member

POST https://api.nexmo.com/beta /conversations/:conv_id/members

Path Parameters

  • Key
    Description
    Example
    Default
  • conv_id
    Required | string

    Conversation ID

    None
    None

Request body application/json

  • Key
    Description
    Example
    Default
  • user_id
    Required | string

    None

    None
    None
  • user_name
    Required | string

    None

    None
    None
  • member_id
    Required | string

    None

    None
    None
  • channel
    Required | string

    None

    None
    None
  • media
    Required | string

    None

    None
    None
  • action
    string

    None


    Must be one of: inviteorjoin
    None
    None

View response field descriptions


201 HTTP response

{
  "id": "abc123",
  "user_id": "abc123",
  "state": "abc123",
  "timestamp": "abc123",
  "channel": "abc123",
  "href": "abc123"
}

400 HTTP response

Retrieve a member

GET https://api.nexmo.com/beta /conversations/:conv_id/members/:member_id

Path Parameters

  • Key
    Description
    Example
    Default
  • conv_id
    Required | string

    Conversation ID

    None
    None
  • member_id
    Required | string

    Member ID

    None
    None

View response field descriptions


200 HTTP response

{
  "id": "abc123",
  "href": "abc123"
}

404 HTTP response

Update a member

PUT https://api.nexmo.com/beta /conversations/:conv_id/members/:member_id

Path Parameters

  • Key
    Description
    Example
    Default
  • conv_id
    Required | string

    Conversation ID

    None
    None
  • member_id
    Required | string

    Member ID

    None
    None

Request body application/json

  • Key
    Description
    Example
    Default
  • channel
    string

    None

    None
    None
  • action
    string

    None


    Must be one of: join
    None
    None

View response field descriptions


200 HTTP response

{
  "id": "abc123",
  "href": "abc123"
}

Delete a member

DELETE https://api.nexmo.com/beta /conversations/:conv_id/members/:member_id

Path Parameters

  • Key
    Description
    Example
    Default
  • conv_id
    Required | string

    Conversation ID

    None
    None
  • member_id
    Required | string

    Member ID

    None
    None

View response field descriptions


200 HTTP response

{}

Event

Coming soon

  • Key
    Description
  • id
    string

    Event ID

  • timestamp
    string

    time when event was created

  • href
    string

    None

Example Model

{
  "id": "abc123",
  "timestamp": "abc123",
  "href": "abc123"
}

Create an event

POST https://api.nexmo.com/beta /conversations/:conv_id/events

Path Parameters

  • Key
    Description
    Example
    Default
  • conv_id
    Required | string

    Conversation ID

    None
    None

Request body application/json

  • Key
    Description
    Example
    Default
  • type
    Required | string

    None

    None
    None
  • to
    Required | string

    None

    None
    None
  • from
    Required | string

    None

    None
    None
  • body
    object
    None
    • Key
      Description
      Example
      Default

View response field descriptions


201 HTTP response

{
  "id": "abc123",
  "timestamp": "abc123",
  "href": "abc123"
}

400 HTTP response

List events

GET https://api.nexmo.com/beta /conversations/:conv_id/events

Path Parameters

  • Key
    Description
    Example
    Default
  • conv_id
    Required | string

    Conversation ID

    None
    None

View response field descriptions


200 HTTP response

[
  {
    "id": "abc123",
    "type": "abc123",
    "from": "abc123",
    "to": "abc123",
    "body": {},
    "state": "abc123",
    "timestamp": "abc123",
    "href": "abc123"
  }
]

400 HTTP response

404 HTTP response

Retrieve an event

GET https://api.nexmo.com/beta /conversations/:conv_id/events/:event_id

Path Parameters

  • Key
    Description
    Example
    Default
  • conv_id
    Required | string

    Conversation ID

    None
    None
  • event_id
    Required | string

    Event ID

    None
    None

View response field descriptions


200 HTTP response

{
  "id": "abc123",
  "type": "abc123",
  "application_id": "abc123",
  "conversation_id": "abc123",
  "from": "abc123",
  "to": "abc123",
  "body": {},
  "timestamp": "abc123"
}

400 HTTP response

404 HTTP response

Delete an event

DELETE https://api.nexmo.com/beta /conversations/:conv_id/events/:event_id

Path Parameters

  • Key
    Description
    Example
    Default
  • conv_id
    Required | string

    Conversation ID

    None
    None
  • event_id
    Required | string

    Event ID

    None
    None

View response field descriptions


200 HTTP response

{}

400 HTTP response

404 HTTP response

Leg

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.

  • Key
    Description
  • uuid
    Required | string

    Leg ID

  • type
    Required | string

    None

  • conversation_uuid
    string

    None

  • status
    string

    None

  • from
    string

    None

  • to
    string

    None

  • direction
    string

    None

  • rate
    string

    None

  • price
    string

    None

  • duration
    string

    None

  • network
    string

    None

  • start_time
    Required | string

    None

  • end_time
    Required | string

    None

Example Model

{
  "uuid": "abc123",
  "type": "abc123",
  "conversation_uuid": "abc123",
  "status": "abc123",
  "from": "abc123",
  "to": "abc123",
  "direction": "abc123",
  "rate": "abc123",
  "price": "abc123",
  "duration": "abc123",
  "network": "abc123",
  "start_time": "abc123",
  "end_time": "abc123"
}

List legs

GET https://api.nexmo.com/beta /legs

View response field descriptions


200 HTTP response

{
  "count": 1,
  "page_size": 1,
  "record_index": 1,
  "_links": {
    "self": {
      "href": "abc123"
    }
  },
  "_embedded": {
    "conversations": [
      {
        "uuid": "abc123",
        "name": "abc123",
        "href": "abc123"
      }
    ]
  }
}

400 HTTP response

Delete a leg

DELETE https://api.nexmo.com/beta /legs/:leg_id

Path Parameters

  • Key
    Description
    Example
    Default
  • leg_id
    Required | string

    Leg ID

    None
    None

View response field descriptions


200 HTTP response

{}

400 HTTP response