Open and close conversations for a contact, set conversation status, and assign or unassign users (human agents or AI agents) to the conversation.
openapi: 3.0.1
info:
title: Respond.io Developer API
description: >-
REST API for the respond.io omnichannel customer-conversation management
platform. Manage contacts, send and read messages across connected channels,
open and close conversations, assign users, post internal comments, manage
tags and custom fields, and configure webhooks. Requests and responses are
JSON. Contacts are addressed by an identifier of the form `id:{id}`,
`email:{email}`, or `phone:{phone}`.
termsOfService: https://respond.io/terms-and-conditions
contact:
name: Respond.io Support
url: https://developers.respond.io/
version: '2.0'
servers:
- url: https://api.respond.io/v2
security:
- bearerAuth: []
tags:
- name: Contacts
description: Create, read, update, merge, list, and delete contacts.
- name: Messages
description: Send messages to contacts and read message history.
- name: Conversations
description: Open, close, status, and assign conversations.
- name: Comments
description: Internal collaboration comments on a contact.
- name: Tags
description: Workspace tags and contact tag assignment.
- name: Custom Fields
description: Structured contact metadata definitions.
paths:
/contact:
post:
operationId: createContact
tags:
- Contacts
summary: Create a contact
description: Creates a new contact in the workspace.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ContactCreate'
responses:
'200':
description: Contact created.
content:
application/json:
schema:
$ref: '#/components/schemas/Contact'
'429':
$ref: '#/components/responses/RateLimited'
/contact/create_or_update/{identifier}:
post:
operationId: createOrUpdateContact
tags:
- Contacts
summary: Create or update a contact
description: >-
Creates a contact if none matches the identifier, otherwise updates the
existing contact.
parameters:
- $ref: '#/components/parameters/Identifier'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ContactCreate'
responses:
'200':
description: Contact created or updated.
content:
application/json:
schema:
$ref: '#/components/schemas/Contact'
'429':
$ref: '#/components/responses/RateLimited'
/contact/list:
get:
operationId: listContacts
tags:
- Contacts
summary: List contacts
description: Returns a paginated list of contacts in the workspace.
parameters:
- name: cursorId
in: query
description: Cursor id for pagination.
required: false
schema:
type: integer
- name: limit
in: query
description: Number of records to return (max 100).
required: false
schema:
type: integer
default: 10
responses:
'200':
description: A list of contacts.
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/Contact'
pagination:
$ref: '#/components/schemas/Pagination'
'429':
$ref: '#/components/responses/RateLimited'
/contact/{identifier}:
get:
operationId: getContact
tags:
- Contacts
summary: Get a contact
description: Retrieves a single contact by identifier.
parameters:
- $ref: '#/components/parameters/Identifier'
responses:
'200':
description: The contact.
content:
application/json:
schema:
$ref: '#/components/schemas/Contact'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
put:
operationId: updateContact
tags:
- Contacts
summary: Update a contact
description: Updates the fields of an existing contact.
parameters:
- $ref: '#/components/parameters/Identifier'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ContactCreate'
responses:
'200':
description: Contact updated.
content:
application/json:
schema:
$ref: '#/components/schemas/Contact'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
delete:
operationId: deleteContact
tags:
- Contacts
summary: Delete a contact
description: Permanently deletes a contact from the workspace.
parameters:
- $ref: '#/components/parameters/Identifier'
responses:
'200':
description: Contact deleted.
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
/contact/merge:
post:
operationId: mergeContacts
tags:
- Contacts
summary: Merge contacts
description: >-
Merges a secondary contact into a primary contact, consolidating
conversations, tags, and fields onto the primary.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- primaryContactId
- secondaryContactId
properties:
primaryContactId:
type: integer
description: Id of the contact to keep.
secondaryContactId:
type: integer
description: Id of the contact merged into the primary.
responses:
'200':
description: Contacts merged.
content:
application/json:
schema:
$ref: '#/components/schemas/Contact'
'429':
$ref: '#/components/responses/RateLimited'
/contact/{identifier}/tag:
post:
operationId: addContactTags
tags:
- Tags
summary: Add tags to a contact
description: Adds one or more tags to a contact.
parameters:
- $ref: '#/components/parameters/Identifier'
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
type: string
example:
- vip
- newsletter
responses:
'200':
description: Tags added.
'429':
$ref: '#/components/responses/RateLimited'
delete:
operationId: removeContactTags
tags:
- Tags
summary: Remove tags from a contact
description: Removes one or more tags from a contact.
parameters:
- $ref: '#/components/parameters/Identifier'
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
type: string
responses:
'200':
description: Tags removed.
'429':
$ref: '#/components/responses/RateLimited'
/contact/{identifier}/channel:
get:
operationId: listContactChannels
tags:
- Contacts
summary: List a contact's channels
description: Lists the messaging channels a contact is reachable on.
parameters:
- $ref: '#/components/parameters/Identifier'
responses:
'200':
description: A list of channels.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Channel'
'429':
$ref: '#/components/responses/RateLimited'
/contact/{identifier}/message:
post:
operationId: sendMessage
tags:
- Messages
summary: Send a message
description: >-
Sends a message to a contact through a specific channel. If channelId is
omitted, the message is sent through the last interacted channel.
parameters:
- $ref: '#/components/parameters/Identifier'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MessageSend'
responses:
'200':
description: Message accepted for delivery.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageResult'
'429':
$ref: '#/components/responses/RateLimited'
/contact/{identifier}/message/{messageId}:
get:
operationId: getMessage
tags:
- Messages
summary: Get a message
description: Retrieves a single message from a contact's conversation by message id.
parameters:
- $ref: '#/components/parameters/Identifier'
- name: messageId
in: path
required: true
description: The message identifier.
schema:
type: integer
responses:
'200':
description: The message.
content:
application/json:
schema:
$ref: '#/components/schemas/Message'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
/contact/{identifier}/conversation:
post:
operationId: updateConversationStatus
tags:
- Conversations
summary: Open or close a conversation
description: Opens or closes the conversation for a contact.
parameters:
- $ref: '#/components/parameters/Identifier'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- status
properties:
status:
type: string
enum:
- open
- close
closingNoteId:
type: integer
description: Optional closing note applied when closing.
responses:
'200':
description: Conversation status updated.
content:
application/json:
schema:
$ref: '#/components/schemas/Conversation'
'429':
$ref: '#/components/responses/RateLimited'
/contact/{identifier}/conversation/assignee:
post:
operationId: assignConversation
tags:
- Conversations
summary: Assign or unassign a conversation
description: >-
Assigns a user (human or AI agent) to the contact's conversation, or
unassigns when assignee is null.
parameters:
- $ref: '#/components/parameters/Identifier'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
assignee:
type: string
nullable: true
description: User identifier (email) to assign, or null to unassign.
example: email:agent@example.com
responses:
'200':
description: Conversation assignment updated.
'429':
$ref: '#/components/responses/RateLimited'
/contact/{identifier}/comment:
post:
operationId: createComment
tags:
- Comments
summary: Create a comment
description: >-
Adds an internal comment to a contact's conversation. Comments support
mentioning users and are not delivered to the contact.
parameters:
- $ref: '#/components/parameters/Identifier'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- text
properties:
text:
type: string
description: Comment body. Use @[email] to mention a user.
example: Following up @[agent@example.com]
responses:
'200':
description: Comment created.
'429':
$ref: '#/components/responses/RateLimited'
/tag:
post:
operationId: createTag
tags:
- Tags
summary: Create a tag
description: Creates a new workspace tag.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Tag'
responses:
'200':
description: Tag created.
content:
application/json:
schema:
$ref: '#/components/schemas/Tag'
'429':
$ref: '#/components/responses/RateLimited'
/tag/{tagId}:
put:
operationId: updateTag
tags:
- Tags
summary: Update a tag
description: Updates an existing workspace tag.
parameters:
- name: tagId
in: path
required: true
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Tag'
responses:
'200':
description: Tag updated.
'429':
$ref: '#/components/responses/RateLimited'
delete:
operationId: deleteTag
tags:
- Tags
summary: Delete a tag
description: Deletes a workspace tag.
parameters:
- name: tagId
in: path
required: true
schema:
type: integer
responses:
'200':
description: Tag deleted.
'429':
$ref: '#/components/responses/RateLimited'
/custom_field:
get:
operationId: listCustomFields
tags:
- Custom Fields
summary: List custom fields
description: Lists all custom field definitions in the workspace.
responses:
'200':
description: A list of custom fields.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/CustomField'
'429':
$ref: '#/components/responses/RateLimited'
post:
operationId: createCustomField
tags:
- Custom Fields
summary: Create a custom field
description: Creates a new custom field definition.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CustomField'
responses:
'200':
description: Custom field created.
content:
application/json:
schema:
$ref: '#/components/schemas/CustomField'
'429':
$ref: '#/components/responses/RateLimited'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
API Access Token from Settings > Integrations > Developer API, sent in
the Authorization header as `Bearer {token}`.
parameters:
Identifier:
name: identifier
in: path
required: true
description: >-
Contact identifier in the form id:{id}, email:{email}, or phone:{phone}.
schema:
type: string
example: phone:+60123456789
responses:
NotFound:
description: Resource not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
RateLimited:
description: Too many requests. Limited to 5 requests per second per method.
headers:
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
Contact:
type: object
properties:
id:
type: integer
description: System-assigned contact id.
firstName:
type: string
lastName:
type: string
email:
type: string
format: email
phone:
type: string
language:
type: string
profilePic:
type: string
format: uri
countryCode:
type: string
status:
type: string
description: Lifecycle stage of the contact.
assignee:
type: string
nullable: true
created:
type: integer
description: Unix timestamp when the contact was created.
tags:
type: array
items:
type: string
customFields:
type: array
items:
$ref: '#/components/schemas/CustomFieldValue'
ContactCreate:
type: object
properties:
firstName:
type: string
lastName:
type: string
email:
type: string
format: email
phone:
type: string
language:
type: string
profilePic:
type: string
format: uri
countryCode:
type: string
customFields:
type: array
items:
$ref: '#/components/schemas/CustomFieldValue'
CustomFieldValue:
type: object
properties:
name:
type: string
value:
type: string
CustomField:
type: object
properties:
id:
type: integer
name:
type: string
type:
type: string
enum:
- text
- number
- date
- list
- checkbox
- url
options:
type: array
items:
type: string
description: Allowed values when type is list.
Tag:
type: object
properties:
id:
type: integer
name:
type: string
required:
- name
Channel:
type: object
properties:
id:
type: integer
name:
type: string
source:
type: string
description: Channel source such as whatsapp, messenger, telegram, email, sms.
meta:
type: object
additionalProperties: true
MessageSend:
type: object
required:
- message
properties:
channelId:
type: integer
description: Target channel id. Omit to use the last interacted channel.
message:
$ref: '#/components/schemas/MessageContent'
MessageContent:
type: object
required:
- type
properties:
type:
type: string
enum:
- text
- attachment
- quick_reply
- whatsapp_template
text:
type: string
description: Body text for type text or quick_reply.
attachment:
type: object
properties:
type:
type: string
enum:
- image
- video
- audio
- file
url:
type: string
format: uri
quickReplies:
type: array
items:
type: object
properties:
title:
type: string
payload:
type: string
template:
type: object
description: WhatsApp template payload (name, languageCode, components).
additionalProperties: true
MessageResult:
type: object
properties:
messageId:
type: integer
status:
type: string
example: queued
Message:
type: object
properties:
messageId:
type: integer
contactId:
type: integer
channelId:
type: integer
traffic:
type: string
enum:
- incoming
- outgoing
message:
$ref: '#/components/schemas/MessageContent'
timestamp:
type: integer
status:
type: string
description: Delivery status (sent, delivered, read, failed).
Conversation:
type: object
properties:
contactId:
type: integer
status:
type: string
enum:
- open
- close
assignee:
type: string
nullable: true
opened:
type: integer
closed:
type: integer
nullable: true
Pagination:
type: object
properties:
cursorId:
type: integer
nullable: true
hasMore:
type: boolean
Error:
type: object
properties:
message:
type: string
status:
type: integer