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
  • id
    Required | string

    Conversation ID

  • href
    Required | string

    URL to the conversation

Example Model

{
  "id": "abc123",
  "href": "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.

    None
    None
  • display_name
    Required | string

    None

    None
    None
  • image_url
    Required | string

    None

    None
    None
  • numbers
    object
    None
    • Key
      Description
      Example
      Default
    • pstn
      string

      None

      None
      None
    • sms
      string

      None

      None
      None
    • sip
      string

      None

      None
      None
  • properties
    object
    None
    • Key
      Description
      Example
      Default
    • ttl
      string

      None

      None
      None

201 HTTP response

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

400 HTTP response

List conversations

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

Request body application/json

  • Key
    Description
    Example
    Default
  • name
    string

    None

    None
    None
  • date_start
    string (dateTime)

    None

    None
    None
  • date_end
    string (dateTime)

    None

    None
    None
  • page_size
    number

    None


    Must be between 1 and 100
    None
    None
  • record_index
    number

    None


    Must be at least 0
    None
    None
  • order
    string

    None


    Must be one of: asc, desc, ASCorDESC
    None
    None

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

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.

    None
    None
  • display_name
    string

    None

    None
    None
  • image_url
    string

    None

    None
    None
  • numbers
    object
    None
    • Key
      Description
      Example
      Default
    • pstn
      string

      None

      None
      None
    • sms
      string

      None

      None
      None
    • sip
      string

      None

      None
      None
  • properties
    object
    None
    • Key
      Description
      Example
      Default
    • ttl
      string

      None

      None
      None

200 HTTP response

{
  "id": "abc123",
  "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

200 HTTP response

{
  "uuid": "abc123",
  "name": "abc123",
  "display_name": "abc123",
  "image_url": "abc123",
  "timestamp": "abc123",
  "sequence_number": "abc123",
  "numbers": {
    "pstn": "abc123",
    "sms": "abc123",
    "sip": "abc123"
  },
  "properties": {
    "ttl": "abc123"
  },
  "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

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

201 HTTP response

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

400 HTTP response

List users

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

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

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

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

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

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

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

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

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

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

200 HTTP response

{}

Event

Coming soon

  • Key
    Description
  • id
    string

    Event ID

  • timestamp
    string

    None

  • 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

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

Request body application/json

  • Key
    Description
    Example
    Default
  • start_id
    string

    None

    None
    None
  • end_id
    string

    None

    None
    None

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

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

Request body application/json

  • Key
    Description
    Example
    Default
  • from
    string

    None

    None
    None

200 HTTP response

{}

400 HTTP response

404 HTTP response