Skip to main content
  1. Assembled
  2. Integrations
  3. Assembled API and data exports

Conversation uploads

Updated

Plans and permissions:

  • Upload conversations from a CSV file: Admin role, or a custom role with Upload conversations set to Can upload conversations via the upload page
  • Upload conversations through the API: Admin role, or a custom role with Assembled API keys set to Create, edit, and delete API keys
  • Link team members to their conversations: Admin or Manager role, or a custom role with Manage team set to Create, edit, or delete any person or Create, edit, or delete certain people

Use conversation uploads to get conversation data into Assembled when it doesn’t come from an integration, such as from a platform Assembled doesn’t integrate with, or for back-office work. Assembled uses uploaded conversations for forecasting and reporting, the same as conversations from your integrations, which Assembled imports automatically.

You can upload a CSV file on Report > Support volume, or send conversations through the Assembled API.

How conversation uploads work

  • Each conversation needs a unique Import ID. If you upload a conversation with an Import ID that’s already in Assembled, Assembled updates it instead of adding a duplicate.
  • A CSV upload can’t change a conversation’s Created at time. To fix one, for example after uploading with the wrong time zone, contact our team.
  • Uploaded data can take up to 24 hours to appear in reports. To have it appear sooner, contact our team.
  • To delete uploaded conversations, contact our team.
  • To link conversations to team members for reports such as Team performance and Agent scorecard, give each team member an API ID. See Link team members to their conversations.
  • For historical Amazon Connect data, use the Amazon Connect upload instead. See Historical Amazon Connect contact data.

Upload conversations from a CSV file

  1. Go to Report > Support volume and select Upload conversations. If it isn’t at the top of the page, open the More actions menu to find it.
  2. To see the columns to use, select Download example file.
  3. Drag your CSV file into the upload area, or select Browse files… and choose it.
  4. Match each field to a column in your file. You need at least the required fields below.
  5. Choose the Time zone of the dates and times in your file.
  6. Select Continue, check the upload, and confirm it.

The Support volume page with the More actions menu open, showing Upload conversations

The Upload conversations window with the drag-and-drop area, the Browse files button, the Download example file link, and an example table of the columns

When the upload finishes, you see Conversations uploaded. If you get errors you can’t fix, chat with our team.

Field Required What it contains
Created at Yes When the conversation was created, in the form YYYY-MM-DD HH:MM:SS
Import ID Yes A unique ID for the conversation, such as the ID of the ticket in your platform
Channel Yes phone, email, or chat
Status Yes The conversation’s status when you upload it: open, pending, or solved
Assignee import ID No The ID of the team member who handled the conversation, as set in their API ID
First responded at No When a team member first responded, in the form YYYY-MM-DD HH:MM:SS
Handle time No How long it took a team member to solve the conversation, in seconds
Solved at No When the conversation was solved, in the form YYYY-MM-DD HH:MM:SS
Tags No Comma-separated tags. Assembled uses them to sort conversations into queues if you’ve set up queues with queue rules. See Queues and exclusions.
Queue No The name of a queue in Assembled. Assembled uses it only if you’ve set up that queue.

Upload conversations through the API

Use the API instead of a CSV file when you want to send conversations automatically, such as from a script that runs every day, or when you have more conversations than is practical to upload by hand. Send them to POST /v0/conversations/bulk. Include when the conversation was first responded to and solved, if you have them: Assembled uses them for SLA tracking and average handle time. To link conversations to team members, set each conversation’s assignee to the team member’s API ID, described below.

To see uploaded conversations in reports such as Team performance and Agent scorecard, give each team member an API ID that matches the assignee import ID in your conversations. Use the exact same ID in both places. You can set it in any of these ways, and mix them.

Set API IDs through the API

Use PATCH /v0/people/:id to update a person, or POST /v0/people to create one, with the ID under the api key in platforms:

"platforms": {
  "api": "agent-123"
}

For details, see People in the API documentation. Once at least one person has an API ID, the Edit person panel shows an API ID field under Optional IDs for everyone who can be scheduled.

Set API IDs by CSV upload

Important: Include each person’s current values in every column you map. An empty cell in a mapped column can overwrite an existing value with a blank one.

  1. Go to Manage team > People management and select Add people > Import from CSV file.
  2. In your CSV file, add an API ID column, and fill it in for every staffable team member. Each row also needs the person’s Email and Role.
  3. In Import people from CSV file, map that column to the API ID field and upload the file.

Assembled matches each row to a person by email and updates them right away. For more about uploading people data, see People management.

Set API IDs on a person’s profile

  1. Go to Manage team > People management and open the person.
  2. Under Optional IDs, enter the ID in API ID.
  3. Select Save changes.

You see Saved changes to followed by the person’s name.

Related articles

Still have questions?