Nexmo Stitch API


Nexmo Stitch API

Version: 1.6.0   •   License: Nexmo Stitch API   •   Contact: Nexmo DevRel, devrel@nexmo.com


Nexmo Stitch API

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.

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.

Create a conversation

POST /conversations

Request


Request Body: [application/json]
Conversation Request Payload Object

Property

Required

Type

Description

name

false

string

Unique name for a conversation

display_name

false

string

The display name for the conversation. It does not have to be unique

image_url

false

string

A link to an image for conversations' and users' avatars

numbers

false

object

An object containing number on different channels.

properties

false

object

Conversation properties



Responses

201   Create / Update Conversation Response Payload Object


Response Body: [application/json]

Property

Required

Type

Description

id

false

string

The unique identifier for this conversation

href

false

string

A link towards a conversation included in Conversation Service API

List conversations

GET /conversations

Request


Query Parameters
date_start [string]

Return the records that occurred after this point in time.

date_end [string]

Return the records that occurred before this point in time.

page_size [number]

Return this amount of records in the response

record_index [number]

Return calls from this index in the response

order [string]

Return the records in ascending or descending order.



Responses

200   List Conversations Response Payload Object.


Response Body: [application/json]

Property

Required

Type

Description

count

false

number

The total number of records returned by your request.

page_size

false

number

The amount of records returned in this response

record_index

false

number

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.

_links

false

object

A series of links between resources in this API in the

http://stateless.co/hal_specification.html

.

_embedded

false

object

A list of conversation objects. See the get details of a specific conversation(#retrieveConversation) response fields for a description of the nested objects

Update a conversation

PUT /conversations/{conversation_id}

Request


Path Parameters
conversation_id [string]
required

Conversation ID

Request Body: [application/json]
Conversation Request Payload Object

Property

Required

Type

Description

name

false

string

Unique name for a conversation

display_name

false

string

The display name for the conversation. It does not have to be unique

image_url

false

string

A link to an image for conversations' and users' avatars

numbers

false

object

An object containing number on different channels.

properties

false

object

Conversation properties



Responses

200   Create / Update Conversation Response Payload Object


Response Body: [application/json]

Property

Required

Type

Description

id

false

string

The unique identifier for this conversation

href

false

string

A link towards a conversation included in Conversation Service API

Retrieve a conversation

GET /conversations/{conversation_id}

Request


Path Parameters
conversation_id [string]
required

Conversation ID



Responses

200   Retrieve a conversation


Response Body: [application/json]

Property

Required

Type

Description

uuid

false

string

The unique identifier for this conversation

name

false

string

Unique name for a conversation

display_name

false

string

The display name for the conversation. It does not have to be unique

timestamp

false

object


sequence_number

false

string

The last Event ID in this conversation. This ID can be used to retrieve a specific event(#getEvent)

members

false

object[]

Users associated to this conversation as members

api_key

false

string

The API key for your account

_links

false

object


Delete a conversation

DELETE /conversations/{conversation_id}

Request


Path Parameters
conversation_id [string]
required

Conversation ID



Responses

200   Success response with empty JSON


Response Body: [application/json]

Property

Required

Type

Description

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.

List users

GET /users

Responses

200   List of users


Response Body: [application/json]

Property

Required

Type

Description

Create a user

POST /users

Request


Request Body: [application/json]

Property

Required

Type

Description

name

false

string

Unique name for a user

display_name

false

string

A string to be displayed as user name. It does not need to be unique

image_url

false

string

A link to an image for conversations' and users' avatars

channels

false

object

When a user joins a conversation as a member, they can have one channel per membership. Channels can be `app`, `phone`, `sip`, or `websocket`



Responses

200   Create a user response


Response Body: [application/json]

Property

Required

Type

Description

name

false

string

Unique name for a user

display_name

false

string

A string to be displayed as user name. It does not need to be unique

Retrieve a user

GET /users/{user_id}

Request


Path Parameters
user_id [string]
required

User ID



Responses

200   Retrieve a user


Response Body: [application/json]

Property

Required

Type

Description

id

false

string

User ID

name

false

string

Unique name for a user

Update a user

PUT /users/{user_id}

Request


Path Parameters
user_id [string]
required

User ID

Request Body: [application/json]

Property

Required

Type

Description

name

false

string

Unique name for a user

display_name

false

string

A string to be displayed as user name. It does not need to be unique

image_url

false

string

A link to an image for conversations' and users' avatars

channels

false

object

When a user joins a conversation as a member, they can have one channel per membership. Channels can be `app`, `phone`, `sip`, or `websocket`



Responses

200   Retrieve a user


Response Body: [application/json]

Property

Required

Type

Description

id

false

string

User ID

href

false

string

A link towards a user included in Conversation Service API

Delete a user

DELETE /users/{user_id}

Request


Path Parameters
user_id [string]
required

User ID



Responses

200   Success response with empty JSON


Response Body: [application/json]

Property

Required

Type

Description

List user conversations

GET /users/{user_id}/conversations

Request


Path Parameters
user_id [string]
required

User ID



Responses

200   List user conversations


Response Body: [application/json]

Property

Required

Type

Description

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.

List members

GET /conversations/{conversation_id}/members

Request


Path Parameters
conversation_id [string]
required

Conversation ID



Responses

200   Members List Object


Response Body: [application/json]

Property

Required

Type

Description

Create a member

POST /conversations/{conversation_id}/members

Request


Path Parameters
conversation_id [string]
required

Conversation ID

Request Body: [application/json]

Property

Required

Type

Description

action

false

string

Invite or join a member to a conversation

user_id

false

string

User ID

member_id

false

string

Member ID

channel

false

object

When a user joins a conversation as a member, they can have one channel per membership. Channels can be `app`, `phone`, `sip`, or `websocket`

media

false

object

Media Object

knocking_id

false

string

Knocker ID. A knocker is a pre-member of a conversation who does not exist yet

member_id_inviting

false

string

Member ID of the member that sends the invitation



Responses

201   Create or invite Member in invite state


Response Body: [application/json]

Property

Required

Type

Description

id

false

string

Member ID

user_id

false

string

User ID

state

false

string

The state that the member is in. Possible values are `invited`, `joined`, `left`, or `unknown`

timestamp

false

object


channel

false

object

When a user joins a conversation as a member, they can have one channel per membership. Channels can be `app`, `phone`, `sip`, or `websocket`

href

false

string

A link towards a member included in Conversation Service API

Retrieve a member

GET /conversations/{conversation_id}/members/{member_id}

Request


Path Parameters
conversation_id [string]
required

Conversation ID

member_id [string]
required

Member ID



Responses

200   Retrieve member payload


Response Body: [application/json]

Property

Required

Type

Description

id

false

string

Member ID

href

false

string

A link towards a member included in Conversation Service API

Update a member

PUT /conversations/{conversation_id}/members/{member_id}

Request


Path Parameters
conversation_id [string]
required

Conversation ID

member_id [string]
required

Member ID

Request Body: [application/json]

Property

Required

Type

Description

action

false

string

Invite or join a member to a conversation

channel

false

object

When a user joins a conversation as a member, they can have one channel per membership. Channels can be `app`, `phone`, `sip`, or `websocket`



Responses

200   Member retrieved


Response Body: [application/json]

Property

Required

Type

Description

id

false

string

Member ID

href

false

string

A link towards a member included in Conversation Service API

Delete a member

DELETE /conversations/{conversation_id}/members/{member_id}

Request


Path Parameters
conversation_id [string]
required

Conversation ID

member_id [string]
required

Member ID



Responses

200   Success response with empty JSON


Response Body: [application/json]

Property

Required

Type

Description

Event

Events are actions that occur within a conversation. Examples of this includes: Text events from members, or invite events from users

Create an event

POST /conversations/{conversation_id}/events

Request


Path Parameters
conversation_id [string]
required

Conversation ID

Request Body: [application/json]

Property

Required

Type

Description

type

false

string

Event type

to

false

string

Member ID

from

false

string

Member ID

body

false

object

Event Body



Responses

201   Create New Event Response Payload Object


Response Body: [application/json]

Property

Required

Type

Description

id

false

string

Event id. This is a progressive integer

timestamp

false

string

Time of event creation

href

false

string

A link towards a conversation event included in Conversation Service API

List events

GET /conversations/{conversation_id}/events

Request


Path Parameters
conversation_id [string]
required

Conversation ID



Responses

200   Retrieve Events Response Payload Object


Response Body: [application/json]

Property

Required

Type

Description

Retrieve an event

GET /conversations/{conversation_id}/events/{event_id}

Request


Path Parameters
conversation_id [string]
required

Conversation ID

event_id [string]
required

Event ID



Responses

200   Retrieve an event Content Payload


Response Body: event_retrieved [application/json]

Property

Required

Type

Description

id

false

string

Event id. This is a progressive integer

type

false

string

Event type

from

false

string

Member ID

to

false

string

Member ID

body

false

object

Event Body

state

false

string

The state that the member is in. Possible values are `invited`, `joined`, `left`, or `unknown`

timestamp

false

string

Time of creation

href

false

string

A link towards a conversation event included in Conversation Service API

Delete an event

DELETE /conversations/{conversation_id}/events/{event_id}

Request


Path Parameters
conversation_id [string]
required

Conversation ID

event_id [string]
required

Event ID



Responses

200   Success response with empty JSON


Response Body: [application/json]

Property

Required

Type

Description

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.

List legs

GET /legs

Responses

200   List Legs Successfully


Response Body: [application/json]

Property

Required

Type

Description

count

false

number

The total number of records returned by your request.

page_size

false

number

The amount of records returned in this response

record_index

false

number

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.

_links

false

object


_embedded

false

object

A list of conversation objects. See the get details of a specific conversation(#retrieveConversation) response fields for a description of the nested objects

Delete a leg

DELETE /legs/{leg_id}

Request


Path Parameters
leg_id [string]
required

Leg ID



Responses

200   Success response with empty JSON


Response Body: [application/json]

Property

Required

Type

Description

Models

leg_state

Property

Required

Type

Description

conversation_id

Property

Required

Type

Description

member_id

Property

Required

Type

Description

member_id_inviting

Property

Required

Type

Description

member_action

Property

Required

Type

Description

user_id_or_user_name

Property

Required

Type

Description

user_id

Property

Required

Type

Description

name

Property

Required

Type

Description

name_conversation

Property

Required

Type

Description

name_user

Property

Required

Type

Description

href

Property

Required

Type

Description

href_conversation

Property

Required

Type

Description

href_conversations_list

Property

Required

Type

Description

href_member

Property

Required

Type

Description

href_user

Property

Required

Type

Description

href_event

Property

Required

Type

Description

href_rtc

Property

Required

Type

Description

event_id

Property

Required

Type

Description

image_url

Property

Required

Type

Description

display_name

Property

Required

Type

Description

display_name_user

Property

Required

Type

Description

numbers

Property

Required

Type

Description

sms

false

string

phone number used for sms channel

pstn

false

string

phone number used for pstn channel

conversation_properties

Property

Required

Type

Description

speaking_detection_level

false

number


ttl

false

number

Time to leave

Property

Required

Type

Description

self

false

object


Property

Required

Type

Description

self

false

object


page_size

Property

Required

Type

Description

record_index

Property

Required

Type

Description

timestamp

Property

Required

Type

Description

timestamp_created

Property

Required

Type

Description

timestamp_updated

Property

Required

Type

Description

timestamp_destroyed

Property

Required

Type

Description

timestamp_leg_start_time

Property

Required

Type

Description

timestamp_leg_end_time

Property

Required

Type

Description

timestamp_res_event

Property

Required

Type

Description

timestamp_res_conversation

Property

Required

Type

Description

created

false

string

Time of creation

updated

false

string

Time of last update

destroyed

false

string

Time of last update

timestamp_res_member

Property

Required

Type

Description

invited

false

string

Timestamp

joined

false

string

Timestamp

left

false

string

Timestamp

timestamp_obj_leg

Property

Required

Type

Description

start

false

string

Time of creation

end

false

string

Timestamp

request

false

string

Timestamp

member_state

Property

Required

Type

Description

leg_id

Property

Required

Type

Description

channel_number

Property

Required

Type

Description

channel_type

Property

Required

Type

Description

channel

Property

Required

Type

Description

type

false

string

Channel type

leg_id

false

string

The id of the leg. rtc_id and call_id are leg id

from

false

object


to

false

object


leg_ids

false

object[]


media

Property

Required

Type

Description

event_type

Property

Required

Type

Description

event_body

Property

Required

Type

Description

event_retrieved

Property

Required

Type

Description

id

false

string

Event id. This is a progressive integer

type

false

string

Event type

from

false

string

Member ID

to

false

string

Member ID

body

false

object

Event Body

state

false

string

The state that the member is in. Possible values are `invited`, `joined`, `left`, or `unknown`

timestamp

false

string

Time of creation

href

false

string

A link towards a conversation event included in Conversation Service API

knocker_id

Property

Required

Type

Description