If we don't already have a ready solution to migrate from the service you want to opt out of, data can be transferred using the API. To do that, you need to involve developers, but we have written detailed instructions to make it easier for them :)
Before writing a data transfer script
1. Familiarize yourself with the API limits so that the data transfer script does not send requests too often and you do not receive error responses.
The limit on the number of requests depends on your current tariff plan. When the limit is exceeded, an error message "429 Too Many Requests" is displayed.
For customers whose accounts were created before March 5, 2024, the old limits apply: 500 requests per hour per active agent (except for light agents with "view only" access), but at least 1000 requests per hour. For example, if you have 15 active agents, your account limit is 7500 requests per hour.
The final transition to the new limit calculation scheme will take place on June 12, 2024. Set your developers the task to consider the logic changes in the scripts that make requests to the Deskie API.
To avoid exceeding the request limit, your script should check the headers in the response::
rate_limit_per_minute — the maximum number of requests per minute;
api_calls_left — the number of requests remaining in the current limit interval;
retry_after — the number of seconds until the limit resets.
POST, PUT, and DELETE method requests count as two requests within the limit.
2. Do not create users first, and then their cases because when creating a case, we automatically create a user if it is not in the database. This way you can transfer more data without exceeding API limits.
3. You can create cases (and users) only through these channels: Email, Calls, WhatsApp and custom channels. If, when using the service from which you switch to Deskie, you processed cases from other channels (social networks, instant messengers), you will not be able to transfer them.
API methods for data transfer
1.1 Creating a case through the "Email" channel
To create a case, you need to use the appropriate API method (or similar, if you need to attach files to the message from which the correspondence begins). However, depending on who initiated the case, the transferred parameters should be different.
a. The user (your customer) initiated the conversation:
required — user_email, subject, content_html, created_at
optional — user_full_name, staff_id, group_id, status, priority, custom_fields, labels
b. The agent initiated the conversation:
required — user_email, initiator_id, subject, content_html, created_at, case_email_id=-1
optional — user_full_name, staff_id, group_id, status, priority, custom_fields, labels
After sending a valid request to create a case, you should receive a "200" response. It will contain all the details of the case, including case_id, case_number, and user_id. This data must be saved so that later you can view/edit the case data and add responses from the user.
1.2 Adding a message to the case created through the "Email" channel
When creating a case, it contains only the message from which the correspondence with the user began. The remaining messages must be added via a separate API method. In this case, you also need to pass different parameters depending on whose message is being added.
a. User's (customer's) message:
required — content_html, created_at, user_id
optional — no optional parameters
b. Agent's message:
required — content_html, created_at, staff_id, do_not_send_email=true
optional — no optional parameters
If you also have notes (internal comments) in the course of the correspondence, you can add them using a special API method.
1.3 Checking parameters of the case created through the "Email" channel
If, when creating a case, you passed only the required parameters, then after adding all messages, you may need to verify the parameters through the case review method. If you need to change some parameters (set a status, add a label, assign a responsible person, etc.), use the edit method.
2.1 Creating a case through the "Calls" channel
To create a case, you need to use the appropriate API method (or similar, if you need to attach files to the message from which the correspondence begins; for example, a conversation record). However, depending on who initiated the communication, the transferred parameters should be different.
a. The user (your client) initiated the conversation:
required — user_phone, subject, content, created_at
optional — user_full_name, staff_id, group_id, status, priority, custom_fields, labels
b. The employee initiated the communication:
required — user_phone, initiator_id, subject, content, created_at
optional — user_full_name, staff_id, group_id, status, priority, custom_fields, labels
After sending a valid request to create a case, you should receive a "200" response. It will contain all the details of the case, including case_id, case_number, and user_id. This data must be saved so that later you can view/edit the case data and add responses from the user.
2.2 Adding a message to the case created through the "Calls" channel
Usually, there are few messages in cases from the Calls channel, since each of them is created when calling a customer. However, there are a lot of notes (internal comments) in which important points are recorded and discussions with colleagues are held. Therefore, for everything that the customer does not have to see, you need to use the API method for adding notes. If you need to create messages for incoming and outgoing calls within a single case, use the add response API method.
a. User called:
required — content, created_at, user_id
optional — no optional parameters
b. Agent called:
required — content, created_at, staff_id
optional — no optional parameters
2.3 Checking parameters of the case created through the "Calls" channel
If, when creating a case, you passed only the required parameters, then after adding all messages, you may need to verify the parameters through the case review method. If you need to change some parameters (set a status, add a label, assign a responsible person, etc.), use the edit method.
3.1 Creating a case through the custom channel
You can read more about custom channels here.
To create a case, you need to use the appropriate API method (or similar, if you need to attach files to the message from which the correspondence begins). However, depending on who initiated the case, the transferred parameters should be different.
a. The user (your customer) initiated the conversation:
required — user_custom_id, subject, content_html (or content for a custom channel of synchronous type), created_at
optional — user_full_name, staff_id, group_id, status, priority, custom_fields, labels
b. The agent initiated the conversation:
required — user_custom_id, initiator_id, subject, content_html (or content for a custom channel of synchronous type), created_at
optional — user_full_name, staff_id, group_id, status, priority, custom_fields, labels
After sending a valid request to create a case, you should receive a "200" response. It will contain all the details of the case, including case_id, case_number, and user_id. This data must be saved so that later you can view/edit the case data and add responses from the user.
3.2 Adding a message to the case created through the custom channel
When creating a case, it contains only the message from which the correspondence with the user began. The remaining messages must be added via a separate API method. In this case, you also need to pass different parameters depending on whose message is being added.
a. User's (customer's) message:
required — content_html (or content for a custom channel of synchronous type), created_at, user_id
optional — no optional parameters
b. Agent's message:
required — content_html (or content for a custom channel of synchronous type), created_at, staff_id
optional — no optional parameters
If you also have notes (internal comments) in the course of the correspondence, you can add them using a special API method.
3.3 Checking parameters of the case created through the custom channel
If, when creating a case, you passed only the required parameters, then after adding all messages, you may need to verify the parameters through the case review method. If you need to change some parameters (set a status, add a label, assign a responsible person, etc.), use the edit method.