respond.io API reference

New to Corsair? See API access, authentication, and error handling.

Contacts

addTags

contacts.addTags Add tags to a contact Risk: write

await corsair.respondio.api.contacts.addTags({ identifier: 'id:1', tags: ['vip', 'renewal'] });

Input

Name	Type	Required	Description
`identifier`	`string`	Yes	—
`tags`	`string[]`	Yes	The tags to add or remove, 1 to 10.

Output

Name	Type	Required	Description
`contactId`	`number \| null`	No	The ID of the contact the action was performed on.

channels

contacts.channels List the channels a contact has interacted on, whose IDs a custom-payload message needs Risk: read

await corsair.respondio.api.contacts.channels({ identifier: 'id:1' });

Input

Name	Type	Required	Description
`identifier`	`string`	Yes	—
`limit`	`number`	No	Page size, 1 to 99. respond.io defaults to 10.
`cursorId`	`string \| number`	No	Where the page starts: the previous pagination.next URL as it is, or the cursorId value from it.

Output

Name	Type	Required	Description
`items`	`object[] \| null`	No	—
`pagination`	`object \| null`	No	—

items full type

{
  id?: number | null,
  name?: string | null,
  source?: string | null,
  meta?: Record<string, JsonValue> | null,
  lastMessageTime?: number | null,
  lastIncomingMessageTime?: number | null,
  created_at?: number | null
}[] | null

pagination full type

{
  next?: string | null,
  previous?: string | null
} | null

create

contacts.create Create a contact at an identifier; respond.io needs processing time afterwards, so wait before acting on it Risk: write

await corsair.respondio.api.contacts.create({ identifier: 'phone:+60123456789', firstName: 'Muhammad', email: 'test@example.com', countryCode: 'MY' });

Input

Name	Type	Required	Description
`firstName`	`string`	Yes	—
`lastName`	`string \| null`	No	—
`phone`	`string \| null`	No	In E.164 form, such as +60123456789.
`email`	`string \| null`	No	—
`language`	`string \| null`	No	An ISO 639-1 language code, such as en or ms.
`profilePic`	`string \| null`	No	—
`countryCode`	`string \| null`	No	An ISO 3166-1 alpha-2 country code, such as MY or US.
`custom_fields`	`object[] \| null`	No	—
`identifier`	`string`	Yes	The contact to create, such as id:123 or phone:+60123456789.

custom_fields full type

{
  name: string,
  value?: string | number | null
}[] | null

Output

Name	Type	Required	Description
`code`	`number \| string \| null`	No	200 on success.
`message`	`string \| null`	No	—

delete

contacts.delete Delete a contact and its conversation history Risk: destructive · Irreversible

await corsair.respondio.api.contacts.delete({ identifier: 'id:12345' });

Input

Name	Type	Required	Description
`identifier`	`string`	Yes	—

Output

Name	Type	Required	Description
`contactId`	`number \| null`	No	The ID of the contact the action was performed on.

deleteTags

contacts.deleteTags Remove tags from a contact Risk: write

await corsair.respondio.api.contacts.deleteTags({ identifier: 'id:1', tags: ['vip'] });

Input

Name	Type	Required	Description
`identifier`	`string`	Yes	—
`tags`	`string[]`	Yes	The tags to add or remove, 1 to 10.

Output

Name	Type	Required	Description
`contactId`	`number \| null`	No	The ID of the contact the action was performed on.

get

contacts.get Read one contact by id:, email: or phone: identifier, with its fields, tags, assignee and lifecycle Risk: read

await corsair.respondio.api.contacts.get({ identifier: 'id:12345' });

Input

Name	Type	Required	Description
`identifier`	`string`	Yes	id:123, email:a@b.com or phone:+60123456789. A bare value is treated as an ID.

Output

Name	Type	Required	Description
`firstName`	`string`	Yes	—
`lastName`	`string \| null`	No	—
`phone`	`string \| null`	No	In E.164 form, such as +60123456789.
`email`	`string \| null`	No	—
`language`	`string \| null`	No	An ISO 639-1 language code, such as en or ms.
`profilePic`	`string \| null`	No	—
`countryCode`	`string \| null`	No	An ISO 3166-1 alpha-2 country code, such as MY or US.
`custom_fields`	`object[] \| null`	No	—
`id`	`number \| null`	No	The contact ID.
`status`	`string \| null`	No	The conversation status: open, closed or blocked.
`tags`	`string[] \| null`	No	Up to 10 tags.
`assignee`	`object \| null`	No	—
`lifecycle`	`string \| null`	No	The lifecycle stage name, such as Hot Lead.
`created_at`	`number \| null`	No	Unix timestamp in seconds.
`isBlocked`	`boolean \| null`	No	—
`locale`	`string \| null`	No	—

custom_fields full type

{
  name: string,
  value?: string | number | null
}[] | null

assignee full type

{
  id?: number | null,
  firstName?: string | null,
  lastName?: string | null,
  email?: string | null,
  role?: string | null,
  team?: {
    id?: number | null,
    name?: string | null
  } | null,
  restrictions?: string[] | null
} | null

lifecycle

contacts.lifecycle Move a contact to a lifecycle stage by name, or clear it with null Risk: write

await corsair.respondio.api.contacts.lifecycle({ identifier: 'id:1', name: 'Hot Lead' });

Input

Name	Type	Required	Description
`identifier`	`string`	Yes	—
`name`	`string \| null`	Yes	The lifecycle stage to move the contact to. null removes the stage.

Output

Name	Type	Required	Description
`code`	`number \| string \| null`	No	200 on success.
`message`	`string \| null`	No	—

list

contacts.list List contacts with an

and or

or filter over fields, tags and lifecycle, a free-text search, and cursor paging Risk: read

await corsair.respondio.api.contacts.list({ filter: { $and: [{ category: 'contactTag', field: 'vip', operator: 'hasAnyOf', value: ['vip'] }] }, timezone: 'Asia/Kuala_Lumpur', limit: 50 });

Input

Name	Type	Required	Description
`filter`	`object`	No	Every condition in $and must hold; any one in$ or must. Defaults to no conditions.
`search`	`string`	No	A free-text search across the contacts. Defaults to empty, which matches every contact.
`timezone`	`string`	No	An IANA timezone used to interpret any timestamp condition, such as Asia/Kuala_Lumpur. Defaults to UTC.
`limit`	`number`	No	Page size, 1 to 99. respond.io defaults to 10.
`cursorId`	`string \| number`	No	Where the page starts: the previous pagination.next URL as it is, or the cursorId value from it.

filter full type

{
  $and?: {
    category: contactField | contactTag | lifecycle,
    field: string,
    operator: isEqualTo | isNotEqualTo | isTimestampAfter | isTimestampBefore | isTimestampBetween | exists | doesNotExist | isGreaterThan | isLessThan | isBetween | hasAnyOf | hasAllOf | hasNoneOf,
    value?: string | string[] | {
      from: string,
      to: string
    }
  }[],
  $or?: {
    category: contactField | contactTag | lifecycle,
    field: string,
    operator: isEqualTo | isNotEqualTo | isTimestampAfter | isTimestampBefore | isTimestampBetween | exists | doesNotExist | isGreaterThan | isLessThan | isBetween | hasAnyOf | hasAllOf | hasNoneOf,
    value?: string | string[] | {
      from: string,
      to: string
    }
  }[]
}

Output

Name	Type	Required	Description
`items`	`object[] \| null`	No	—
`pagination`	`object \| null`	No	—

items full type

{
  firstName: string,
  lastName?: string | null,
  phone?: string | null,
  email?: string | null,
  language?: string | null,
  profilePic?: string | null,
  countryCode?: string | null,
  custom_fields?: {
    name: string,
    value?: string | number | null
  }[] | null,
  id?: number | null,
  status?: string | null,
  tags?: string[] | null,
  assignee?: {
    id?: number | null,
    firstName?: string | null,
    lastName?: string | null,
    email?: string | null,
    role?: string | null,
    team?: {
      id?: number | null,
      name?: string | null
    } | null,
    restrictions?: string[] | null
  } | null,
  lifecycle?: string | null,
  created_at?: number | null,
  isBlocked?: boolean | null,
  locale?: string | null
}[] | null

pagination full type

{
  next?: string | null,
  previous?: string | null
} | null

merge

contacts.merge Merge two contacts by their IDs, setting the merged fields; the older contact stays and the other is removed Risk: destructive · Irreversible

await corsair.respondio.api.contacts.merge({ contactIds: [1, 2], firstName: 'Muhammad', email: 'test@example.com' });

Input

Name	Type	Required	Description
`firstName`	`string`	Yes	—
`lastName`	`string \| null`	No	—
`phone`	`string \| null`	No	In E.164 form, such as +60123456789.
`email`	`string \| null`	No	—
`language`	`string \| null`	No	An ISO 639-1 language code, such as en or ms.
`profilePic`	`string \| null`	No	—
`countryCode`	`string \| null`	No	An ISO 3166-1 alpha-2 country code, such as MY or US.
`custom_fields`	`object[] \| null`	No	—
`contactIds`	`[number, number]`	Yes	The IDs of the two contacts to merge. The older one survives; the other is removed.

custom_fields full type

{
  name: string,
  value?: string | number | null
}[] | null

Output

Name	Type	Required	Description
`contactId`	`number \| null`	No	The ID of the contact the action was performed on.

update

contacts.update Update a contact’s fields by identifier Risk: write

await corsair.respondio.api.contacts.update({ identifier: 'id:12345', firstName: 'Updated' });

Input

Name	Type	Required	Description
`identifier`	`string`	Yes	—
`firstName`	`string`	No	—
`lastName`	`string \| null`	No	—
`phone`	`string \| null`	No	—
`email`	`string \| null`	No	—
`language`	`string \| null`	No	An ISO 639-1 language code, such as en or ms.
`profilePic`	`string \| null`	No	—
`countryCode`	`string \| null`	No	An ISO 3166-1 alpha-2 country code, such as MY or US.
`custom_fields`	`object[] \| null`	No	—

custom_fields full type

{
  name: string,
  value?: string | number | null
}[] | null

Output

Name	Type	Required	Description
`contactId`	`number \| null`	No	The ID of the contact the action was performed on.

upsert

contacts.upsert Create or update a contact in one call, which is the safe choice when you do not know whether it exists Risk: write

await corsair.respondio.api.contacts.upsert({ identifier: 'email:a@b.com', firstName: 'A', custom_fields: [{ name: 'Plan', value: 'pro' }] });

Input

Name	Type	Required	Description
`firstName`	`string`	Yes	—
`lastName`	`string \| null`	No	—
`phone`	`string \| null`	No	In E.164 form, such as +60123456789.
`email`	`string \| null`	No	—
`language`	`string \| null`	No	An ISO 639-1 language code, such as en or ms.
`profilePic`	`string \| null`	No	—
`countryCode`	`string \| null`	No	An ISO 3166-1 alpha-2 country code, such as MY or US.
`custom_fields`	`object[] \| null`	No	—
`identifier`	`string`	Yes	—

custom_fields full type

{
  name: string,
  value?: string | number | null
}[] | null

Output

Name	Type	Required	Description
`contactId`	`number \| null`	No	The ID of the contact the action was performed on.

Conversations

assign

conversations.assign Assign a contact to a user, or unassign it by sending a null assignee Risk: write

await corsair.respondio.api.conversations.assign({ identifier: 'id:1', assignee: 'jane@example.com' });

Input

Name	Type	Required	Description
`identifier`	`string`	Yes	—
`assignee`	`number \| string \| null`	No	A user ID (from space.listUsers) or a user email. Leave it out or send null to unassign the contact.

Output

Name	Type	Required	Description
`contactId`	`number \| null`	No	The ID of the contact the action was performed on.

status

conversations.status Open or close a contact’s conversation, optionally recording a closing note and summary when closing Risk: write

await corsair.respondio.api.conversations.status({ identifier: 'id:1', status: 'close', category: 'Resolved', summary: 'Handled in one call.' });

Input

Name	Type	Required	Description
`identifier`	`string`	Yes	—
`status`	`open \| close`	Yes	The conversation status to set.
`category`	`string`	No	The closing note name. Only meaningful when closing. Up to 128 characters.
`summary`	`string`	No	A closing summary. Only used when a category is given.

Output

Name	Type	Required	Description
`contactId`	`number \| null`	No	The ID of the contact the action was performed on.

Messages

comment

messages.comment Add an internal comment to a contact, which the customer never sees Risk: write

await corsair.respondio.api.messages.comment({ identifier: 'id:1', text: 'This is a comment' });

Input

Name	Type	Required	Description
`identifier`	`string`	Yes	—
`text`	`string`	Yes	Up to 1000 characters. Mention a user with {{@user.ID}}.

Output

Name	Type	Required	Description
`contactId`	`number \| null`	No	—
`text`	`string \| null`	No	—
`created_at`	`number \| null`	No	Unix timestamp in seconds.

get

messages.get Read one message by id, with its delivery status and sender Risk: read

await corsair.respondio.api.messages.get({ identifier: 'id:1', messageId: 1262965213 });

Input

Name	Type	Required	Description
`identifier`	`string`	Yes	—
`messageId`	`number`	Yes	The message id.

Output

Name	Type	Required	Description
`messageId`	`number \| null`	No	—
`channelMessageId`	`string \| number \| null`	No	The channel’s own id: a string on some, a number on others.
`contactId`	`number \| null`	No	—
`channelId`	`number \| null`	No	—
`traffic`	`string \| null`	No	incoming or outgoing.
`message`	`object \| null`	No	The message body, whose shape follows its type.
`status`	`object[] \| null`	No	—
`sender`	`object \| null`	No	Who sent it.

message full type

{
  type?: string | null
} | null

status full type

{
  value?: string | null,
  timestamp?: number | null,
  message?: string | null
}[] | null

sender full type

{
  source?: string | null
} | null

list

messages.list List a contact’s messages, optionally mixing in its comments; keep paging until pagination.next is null, since a page can be empty with more to come Risk: read

await corsair.respondio.api.messages.list({ identifier: 'id:1', limit: 50, includeComments: true });

Input

Name	Type	Required	Description
`identifier`	`string`	Yes	—
`cursorId`	`string \| number`	No	Where the page starts: the previous pagination.next URL as it is, or the cursorId value from it.
`includeComments`	`boolean`	No	True mixes the contact’s comments into the list, each item then carrying a type of message or comment. A page can be empty while pagination.next is still set, so keep paging until next is null.
`limit`	`number`	No	Page size, at most 50.

Output

Name	Type	Required	Description
`items`	`Record<string, JsonValue>[] \| null`	No	A message or, with includeComments, a comment. Each carries `type` only when includeComments was true.
`pagination`	`object \| null`	No	—

pagination full type

{
  next?: string | null,
  previous?: string | null
} | null

send

messages.send Send a message to a contact, on the last channel it used unless channelId is given; this reaches the customer Risk: write

await corsair.respondio.api.messages.send({ identifier: 'id:12345', channelId: 42, message: { type: 'text', text: 'Your order has shipped.' } });

Input

Name	Type	Required	Description
`identifier`	`string`	Yes	—
`channelId`	`number \| null`	No	The channel to send on. Omit it to use the last channel the contact interacted on; a custom_payload message requires it.
`message`	`object`	Yes	—

message full type

{
  type: text | attachment | custom_payload | quick_reply | whatsapp_template | email | facebook_template,
  text?: string | null,
  messageTag?: ACCOUNT_UPDATE | POST_PURCHASE_UPDATE | CONFIRMED_EVENT_UPDATE | null
}

Output

Name	Type	Required	Description
`messageId`	`number`	Yes	The new message id, for tracking it later.

Space

getUser

space.getUser Read one workspace user by ID Risk: read

await corsair.respondio.api.space.getUser({ id: 67890 });

Input

Name	Type	Required	Description
`id`	`number`	Yes	The user ID.

Output

Name	Type	Required	Description
`id`	`number \| null`	No	—
`firstName`	`string \| null`	No	—
`lastName`	`string \| null`	No	—
`email`	`string \| null`	No	—
`role`	`string \| null`	No	owner, manager or agent.
`team`	`object \| null`	No	—
`restrictions`	`string[] \| null`	No	—

team full type

{
  id?: number | null,
  name?: string | null
} | null

listChannels

space.listChannels List the messaging channels connected in the workspace Risk: read

await corsair.respondio.api.space.listChannels({});

Input

Name	Type	Required	Description
`limit`	`number`	No	Page size, 1 to 99. respond.io defaults to 10.
`cursorId`	`string \| number`	No	Where the page starts: the previous pagination.next URL as it is, or the cursorId value from it.

Output

Name	Type	Required	Description
`items`	`object[] \| null`	No	—
`pagination`	`object \| null`	No	—

items full type

{
  id?: number | null,
  name?: string | null,
  source?: string | null,
  created_at?: number | null
}[] | null

pagination full type

{
  next?: string | null,
  previous?: string | null
} | null

listClosingNotes

space.listClosingNotes List the closing notes a conversation can be closed with, sorted by category Risk: read

await corsair.respondio.api.space.listClosingNotes({});

Input

Name	Type	Required	Description
`limit`	`number`	No	Page size, 1 to 99. respond.io defaults to 10.
`cursorId`	`string \| number`	No	Where the page starts: the previous pagination.next URL as it is, or the cursorId value from it.

Output

Name	Type	Required	Description
`items`	`object[] \| null`	No	—
`pagination`	`object \| null`	No	—

items full type

{
  category?: string | null,
  description?: string | null
}[] | null

pagination full type

{
  next?: string | null,
  previous?: string | null
} | null

listCustomFields

space.listCustomFields List the custom field definitions, whose types a contact write must match Risk: read

await corsair.respondio.api.space.listCustomFields({});

Input

Name	Type	Required	Description
`limit`	`number`	No	Page size, 1 to 99. respond.io defaults to 10.
`cursorId`	`string \| number`	No	Where the page starts: the previous pagination.next URL as it is, or the cursorId value from it.

Output

Name	Type	Required	Description
`items`	`object[] \| null`	No	—
`pagination`	`object \| null`	No	—

items full type

{
  id?: number | null,
  name?: string | null,
  description?: string | null,
  dataType?: string | null,
  allowedValues?: string[] | null
}[] | null

pagination full type

{
  next?: string | null,
  previous?: string | null
} | null

listTemplates

space.listTemplates List the message templates of one connected channel Risk: read

await corsair.respondio.api.space.listTemplates({ channelId: 42 });

Input

Name	Type	Required	Description
`limit`	`number`	No	Page size, 1 to 99. respond.io defaults to 10.
`cursorId`	`string \| number`	No	Where the page starts: the previous pagination.next URL as it is, or the cursorId value from it.
`channelId`	`number`	Yes	The channel whose templates to list.

Output

Name	Type	Required	Description
`items`	`object[] \| null`	No	—
`pagination`	`object \| null`	No	—

items full type

{
  id?: number | null,
  name?: string | null,
  languageCode?: string | null,
  category?: string | null,
  status?: string | null,
  channelId?: number | null,
  components?: Record<string, JsonValue>[] | null
}[] | null

pagination full type

{
  next?: string | null,
  previous?: string | null
} | null

listUsers

space.listUsers List the workspace users Risk: read

await corsair.respondio.api.space.listUsers({ limit: 50 });

Input

Name	Type	Required	Description
`limit`	`number`	No	Page size, 1 to 99. respond.io defaults to 10.
`cursorId`	`string \| number`	No	Where the page starts: the previous pagination.next URL as it is, or the cursorId value from it.

Output

Name	Type	Required	Description
`items`	`object[] \| null`	No	—
`pagination`	`object \| null`	No	—

items full type

{
  id?: number | null,
  firstName?: string | null,
  lastName?: string | null,
  email?: string | null,
  role?: string | null,
  team?: {
    id?: number | null,
    name?: string | null
  } | null,
  restrictions?: string[] | null
}[] | null

pagination full type

{
  next?: string | null,
  previous?: string | null
} | null

Overview

Plugins

respond.io API reference

Contacts

addTags

channels

create

delete

deleteTags

get

lifecycle

list

merge

update

upsert

Conversations

assign

status

Messages

comment

get

list

send

Space

getUser

listChannels

listClosingNotes

listCustomFields

listTemplates

listUsers

​Contacts

​addTags

​channels

​create

​delete

​deleteTags

​get

​lifecycle

​list

​merge

​update

​upsert

​Conversations

​assign

​status

​Messages

​comment

​get

​list

​send

​Space

​getUser

​listChannels

​listClosingNotes

​listCustomFields

​listTemplates

​listUsers

Contacts

addTags

channels

create

delete

deleteTags

get

lifecycle

list

merge

update

upsert

Conversations

assign

status

Messages

comment

get

list

send

Space

getUser

listChannels

listClosingNotes

listCustomFields

listTemplates

listUsers