respond.io API Documentation
Overview
The respond.io Developer API enables developers to seamlessly integrate messaging capabilities into their existing platforms or applications. The API provides a wide range of functionalities such as sending and receiving messages, managing contacts, and automating messaging campaigns. With the flexibility and scalability of the respond.io API, developers can streamline their messaging operations and create unique, tailored messaging experiences for their users.
Our API is built to be user-friendly and easy to understand, through the implementation of REST principles. The API follows RESTful conventions as much as possible and uses common methods like GET, POST, PUT, and DELETE for operations. The request and response bodies are encoded in JSON. Additionally, the API adheres to standard HTTP response codes and requires authentication for all requests to ensure secure and reliable integration.
The base URL for all API requests is api.respond.io/v2, and all requests must be made over HTTPS.
👉 Get Started
Authentication
An API Access Token is used to authenticate the requests. You can view and manage your Access Token in Settings > Integration > Developer API page.
You can generate up to 10 Access Tokens per workspace. Each organization is limited to generate a maximum of 10 Access Tokens.
The authentication is passed via the Authorization header with each request.
Please contact us if you would like to increase your Access Token limit for your organization.
Rate Limiting
respond.io API is subject to rate limiting. The limits are applied on the organization-level.
The API responses contain useful rate limit headers to check the remaining requests.
| Name | Description |
|---|---|
Retry-After | Number of seconds until you can retry the request |
X-RateLimit-Limit | Number of requests allowed for this end point |
X-RateLimit-Remaining | Number of requests remaining for this end point |
Note that when you hit the ratelimit, a 429 (Too Many Requests) HTTP Status Code is returned along with a Retry-After header. These response headers are useful to determine when to make the next API call.
Please contact us if you would like to increase your rate limit.
Rate Limits
| API Name | Endpoint | Requests Per Second |
|---|---|---|
| Send a message | /contact/{identifier}/message | 10 |
| Get a message | /contact/{identifier}/message/{messageId} | 15 |
| Create a comment | /contact/{identifier}/comment | 10 |
| Get a contact | /contact/{identifier} | 10 |
| Create, update or delete a contact | /contact/{identifier} | 5 |
| Merge two contacts | /contact/merge | 5 |
| Create or update a contact | /contact/create_or_update/{identifier} | 5 |
| List the contacts | /contact/list | 5 |
| Add or delete tags | /contact/{identifier}/tag | 5 |
| List contact channels | /contact/{identifier}/channels | 5 |
| Get a contact channel | /contact/{identifier}/channel/{channelId} | 10 |
| Assign/unassign conversation | /contact/{identifier}/conversation/assignee | 5 |
| Open/close conversation | /contact/{identifier}/conversation/status | 5 |
| List space channels | /space/channel | 5 |
| List closing notes | /space/closing_notes | 5 |
| List space users | /space/user | 5 |
| Get a space user | /space/user/{id} | 10 |
| Create custom field | /space/contact_field | 5 |
| Get a custom field | /space/contact_field/{id} | 10 |
| List custom fields | /space/contact_field | 5 |
HTTP Response Codes
| Status Code | Description |
|---|---|
| 200 Ok | The request is successful and the appropriate response has been provided. |
| 201 Created | The request has been fulfilled, resulting in the creation of a new resource. |
| 400 Bad request | There is an error on the client’s side and, as a result, the server cannot return a response. For example, contact email, phone or ID is invalid. |
| 401 Unauthorised | The access token is not valid. |
| 404 Not Found | Given the access token used, the resource does not exist. |
| 429 Too many requests | This request exceeds the number of requests allowed. Slow down and try again. If you need higher rate limit, contact us here. |
| 449 Your request cannot be processed at the moment as it's in the queue. Please try again in a few minutes | This request cannot be processed as the resource is still being created, please try again later. |
| 502/504 timeouts | The upstream server hasn’t provided a timely response to the second server, currently serving as a gateway or proxy. As a result, it cannot provide a response to the client. |
| 503 | The server cannot process the request because it is either overloaded or it is under maintenance. |
Pagination
respond.io API has several endpoints that return lists of items over multiple pages. For performance reasons, the API does not return large record sets all at once. It breaks up the results into smaller subsets and returns them in pages.
The integration can use the pagination.next in another request to receive the next part of the list or pagination.previous to receive the previous part of the list
| Param | Type | Description |
|---|---|---|
| cursorId | integer | (optional) A cursor returned from a previous response, used to request the next page of results. Default: return results from the beginning of the list |
| limit | integer | (optional) The number of items to return. Default: 10 items Max: 100 items |
