APIs & Integrations

Data exports

Table of Contents

Exporting data from Sparkcentral

Our data exports will help you to create custom reports in Excel, or you can use it to import data into your data warehouse for further analysis.

On-Demand exports

We are also exposing IDs in the export files. The Conversation ID field can be found in both the conversations and messages export for example. This will enable you to link these tables – making more advanced analyses available to you.

  1. Navigate to Analytics, Exports,On-Demand (supervisor level access required)
  2. Choose one of the exports from the dropdown
  3. Define the scope of the export (such as time range, timezone and channels) using the filters.
  4. Click on Generate Export. The export will be generated in the background and you will be notified once the export is available. You can also go back to this screen to see the progress of your exports.
  5. Click on the download icon to download the CSV file to your computer

Scheduled exports

The scheduled exports will be made available in .csv format on an SFTP location.

Create a new scheduled export:

  1. Go to Analytics, Exports, Scheduled
  2. Click on Create Scheduled Export
  3. Give the new export a name
  4. Select the type of export from the dropdown
  5. Choose the Timezone: all date/time fields will be updated according to this setting 
  6. Choose the channels for which you would like to export the data
  7. Select the frequency (Hourly, Daily, Weekly) on which the export will automatically be generated and stored on the SFTP location

Path & file names on FTP location:

The root folder of the FTP is called /export. Each specific Scheduled Export will go into a subdirectory in this root folder.

Export TypePath
Resolved Conversations/export/resolved-conversation
Open Conversations/export/open-conversation
Contacts/export/contact
Messages/export/message
Response Times/export/response-times
Tags/export/tag
Teams/export/team
Topics/export/topic
Users/export/user
User Presence/export/user-presence

Examples:

  • /export/topic/[orgId][exportType][from ddMMyyyHHmmss][to ddMMyyyHHmmss][uuid].csv
  • /export/open-conversation/[orgId][exportType][ddMMyyyHHmmss][uuid].csv

FTP access

If you would like to access the Scheduled Exports or Audit Logs for your account you will need to login to an FTP server.

Admins can now create new FTP users and update passwords for existing users. You can find this under Settings – Integration & APIsFTP Users.

The FTP account password will be shown only once. However, you can generate a new password if needed.

FTP servers

US platformsftp://exports.sparkcentral.comPort: 22
EU platformsftp://exports-eu.sparkcentral.comPort: 22

Export definitions

Virtual Agents

This export contains the metrics collected per virtual agent for a selected time range.
Header Description Values
Agent ID The unique Identifier for the Virtual Agent
Agent Name The name of the Virtual Agent, as configured in the Virtual Agent configuration Virtual Agent Name
Medium The specific medium on which the Virtual Agent was part of a conversation Medium Name
Channel The specific channel on which the Virtual Agent was part of a conversation Channel Name
Channel Display Name The custom display name of the channel
Total Conversations The total number of conversations in which the Virtual Agent has sent at least 1 message
Handover to Agent The number of conversations which have been handed over from the Virtual Agent to a Human Agent
Handover due to error The number of conversations that were handed over because the Virtual Agent encountered an error
Resolved The number of conversations which have been resolved by a Virtual Agent
Total Conversations with Topic The number of Topics which the Virtual Agent has applied to conversations
Total Messages Tagged The number of messages that have been tagged.
Total Tags Applied The number of Tags that have been applied.

Resolved Conversations

This export contains all conversations that are resolved for the first time in the selected time range. In the export you will find 1 row per conversation with data that was available for that conversation at the time of the export.
Header Description Values
Conversation ID Unique Identifier for each Conversation
Medium The medium on which the Conversation took place Medium Name
Channel The specific Channel on which the Conversation took place Channel Name
Channel Display Name The custom display name of the channel
Contact Profile ID Unique Identifier for each Contact/Customer
Contact Primary identifier One of the two identifiers of the contacts. Depending on the medium this can be the name / phone number / alias / …
Contact Secondary identifier One of the two identifiers of the contacts. Depending on the medium this can be the name / phone number / alias / …
Created at (Date / Time) Creation date of the Conversation Year-Month-Day HH:MM:SS.MS
Last Status Change Agent ID The unique identifier of the Agent that made the last status change to the Conversation (moving it to Resolved/Pending)
Last Status Change Agent Name The Agent that made the last status change to the Conversation (moving it to Resolved/Pending) First Name – Last Name
Last Status Change Agent Reference Agent’s Internal ID
Last Status Change Team ID The unique identifier of the Team that made the last status change to the Conversation (moving it to Resolved/Pending)
Last Status Change Team Name The Team that made the last status change to the Conversation (moving it to Resolved/Pending) Team Name
Current Status Last Status of the Conversation at the time of the export New / Pending / Resolved
Resolved By Agent/Virtual Agent/Bulk Resolve/System
Resolve Reason The resolve reason selected by the agent
Resolve Comment Any resolve reason comment added by the agent
Resolve Trigger Resolve by Human Agent/Virtual Agent/Automation/Auto Resolve
Resolved At (Date / Time) Date and Timestamp of when the Conversation was resolved Year-Month-Day HH:MM:SS.MS
Resolved Agent ID The unique identifier of the Agent that Resolved the Conversation
Resolved Agent Name Agent that Resolved the Conversation First Name – Last Name
Resolved Agent Reference Agent’s Internal ID
Number of Inbound Messages Total number of messages received from the customer during this conversation
Number of Outbound Messages Total number of messages sent to the customer during this conversation
First Response Time (s) The time between the first inbound and the first outbound or the time between handover from VA/AR to the New queue and the first Human Agent outbound Time in seconds
Handle Time (s) The time that an Agent was actively working on this Conversation (lock) Time in seconds
No-Reply Time (s) The time that an Agent was looking at the Conversation (lock) and resolved it without any reply Time in seconds
Cherry-Picking Time (s) The time that an Agent was looking at the Conversation (lock) and did not send any reply Time in seconds
Resolution Time (s) The time between the first inbound and the status change to Resolved Time in seconds
Topic IDs The unique identifier for the Topics which have been applied to the Conversation
Topic Names The Topics which have been applied to the Conversation Topic Name(s)
Conversation URL The URL to this Conversation in Sparkcentral
Last Updated Date and timestamp of when the last change was made to this Conversation Year-Month-Day HH:MM:SS.MS
Language The language that was detected or set in the conversation. English, French, …
CSAT Score 1- Very unsatisfied
2- Unsatisfied
3- Neutral
4- Satisfied
5- Very satisfied
CSAT Completed Status Successful/ Skipped/ Customer did not respond/ Customer’s response was not recognized
CSAT Follow-up Question Any follow-up survey question sent to the customer
CSAT Follow-up Answer Any follow up answer/feedback received from the customer

Open Conversations

This export contains all conversations with the status New/Pending at the moment of the export. In the export you will find 1 row per conversation with data that was available for that conversation at the time of the export.

HeaderDescriptionValues
Conversation IDUnique Identifier for each Conversation 
MediumThe medium on which the Conversation took placeMedium Name
ChannelThe specific Channel on which the Conversation took placeChannel Name
Channel Display NameThe custom display name of the channel 
Contact Profile IDUnique Identifier for each Contact/Customer 
Contact Primary identifierOne of the two identifiers of the contacts. Depending on the medium this can be the name / phone number / alias / … 
Contact Secondary identifierOne of the two identifiers of the contacts. Depending on the medium this can be the name / phone number / alias / … 
Created at (Date / Time)Creation date of the ConversationYear-Month-Day HH:MM:SS.MS
Last Status Change Agent IDThe unique identifier of the Agent that made the last status change to the Conversation (moving it to Resolved/Pending) 
Last Status Change Agent NameThe Agent that made the last status change to the Conversation (moving it to Resolved/Pending)First Name – Last Name
Last Status Change Agent ReferenceAgent’s Internal ID 
Last Status Change Team IDThe unique identifier of the Team that made the last status change to the Conversation (moving it to Resolved/Pending) 
Last Status Change Team NameThe Team that made the last status change to the Conversation (moving it to Resolved/Pending)Team Name
Current StatusLast Status of the Conversation at the time of the exportNew / Pending / Resolved
Resolved ByType of Agent that resolved the ConversationAgent / Bulk Resolve / Auto-Resolve / System
Resolved At (Date / Time)Date and Timestamp of when the Conversation was resolvedYear-Month-Day HH:MM:SS.MS
Resolve Agent IDThe unique identifier of the Agent that Resolved the Conversation 
Resolve Agent NameAgent that Resolved the ConversationFirst Name – Last Name
Resolved Agent ReferenceAgent’s Internal ID 
Number of Inbound MessagesTotal number of messages sent by the customer during this conversation 
Number of Outbound MessagesTotal number of messages sent to the customer during this conversation 
First Response Time (s)The time between the first inbound and the first outbound or the time between handover from VA/AR to the New queue and the first Human Agent outboundTime in seconds
Handle Time (s)The time that an Agent was actively working on this Conversation (lock)Time in seconds
No-Reply Time (s)The time that an Agent was looking at the Conversation (lock) and resolved it without any replyTime in seconds
Cherry-Picking Time (s)The time that an Agent was looking at the Conversation (lock) and did not send any replyTime in seconds
Resolution Time (s)The time between the first inbound and the status change to ResolvedTime in seconds
Topic IDsThe unique identifier for the Topics which have been applied to the Conversation 
Topic NamesThe Topics which have been applied to the ConversationTopic Name(s)
Conversation URLThe URL to this Conversation in Sparkcentral 
Last UpdatedDate and timestamp of when the last change was made to this ConversationYear-Month-Day HH:MM:SS.MS
LanguageThe language that was detected or set in the conversation.English, French, …

Messages

This export contains all unique messages that have been created in the selected time range. In the export you will find 1 row per message with data that was available for that message at the time of the export.
Header Description Values
Message ID The unique identifier for the message
Created at (Date / Time) Date and Timestamp of when the message was created Year-Month-Day HH:MM:SS.MS
Conversation ID Unique Identifier for each Conversation
Medium The medium on which the message was sent
Channel The specific Channel on which the message was sent
Channel Display Name The custom display name of the channel
Contact Profile ID Unique Identifier for each Contact/Customer
Contact Primary Identifier One of the two identifiers of the contacts. Depending on the medium this can be the name / phone number / alias / …
Contact Secondary identifier One of the two identifiers of the contacts. Depending on the medium this can be the name / phone number / alias / …
Message Type The specific type of the message
Origin Where the message was sent from Sparkcentral / Medium
Outbound Message Type Where the Agent outbound was sent from Reply / Proactive
Direction Where did the message come from Inbound / Outbound
Agent ID The unique identifier of the Agent that has sent the outbound message
Agent Name The Agent that has sent the outbound message First Name – Last Name
Agent Reference The agent’s internal ID
Team ID The unique identifier of the Team
Team Name The Team where the Agent that has sent the outbound message  is a Member of Team Name
Tag IDs The unique identifier of the Tag
Tag Names The Tags which have been applied to the Message Tag Name(s)
Content The message content Twitter-specific: this content is not available in the scheduled exports. The content is available as part of the on-demand exports.
Conversation URL The URL to this Conversation in Sparkcentral
Post URL URL to the original inbound in the medium (natively)
Last Updated The date and time on which the message was last updated from Sparkcentral.
Deleted at The date and time on which the message was deleted from Sparkcentral.

Teams

This export contains data on a team level. Only teams that have at least one outbound message will be available in the export. In the export you will find 1 row per team with data that was available at the time of the export.
Header Description Values
Created At Date and Timestamp of when an Agent of this Team has sent the first outbound message. Year-Month-Day HH:MM:SS.MS
Team ID The unique identifier of the Team which has been active
Team Name The Team which has been active Team Name
Resolves With Reply The total number of conversations which have been resolved by Agents of this Team and has at least 1 outbound message
Resolves without Reply The total number of conversations which have been resolved by Agents of this Team without an outbound message
Avg. First Response Time (s) The Average First Response Time of all Conversations which have been handled by Agents of this Team in the selected time range Time in seconds
Avg. Resolution Time (s) The Average Resolution Time of all Conversations which have been handled by this Team in the selected time range Time in seconds
Total Handle Time (s) The total time that Agents of this Team were actively working on Conversations (lock) Time in seconds
Total No-Reply Time (s) The total time that Agents of this Team were looking at Conversations (lock) and resolved it without any reply Time in seconds
Total Cherry-Picking Time (s) The total time that Agents of this Team were looking at Conversations (lock) and did not send any reply Time in seconds
Avg. Handle Time (s) The average of the time that Agents of this Team were actively working on Conversations (lock) Time in seconds
Contacts Helped The number of contacts/customers that received at least 1 inbound from an Agent of this Team

Contacts

All contacts that have at least 1 message in the selected time range.
Header Description Values
Contact Profile ID The unique identifier for each Contact/Customer within Sparkcentral
Medium The Medium on which the Contact has sent a message Medium Name
Primary identifier One of the two identifiers of the contacts. Depending on the medium this can be the name / phone number / alias / …
Secondary identifier One of the two identifiers of the contacts. Depending on the medium this can be the name / phone number / alias / …
Created At The date & time when the Contact has sent the 1st message within the selected time range Year-Month-Day HH:MM:SS.MS
Number of Conversations The number of conversations with this Contact/Customer
Number of Inbound Messages The number of messages sent by this Contact/Customer
Number of Outbound Messages The number of messages sent to this Contact/Customer
Last Updated Date and Timestamp of the last update of this Contact/Cstomer Year-Month-Day HH:MM:SS.MS

Topics

All Topics that have at least one application in the selected time range.
Header Description Values
Topic ID The unique identifier for each Topic
Topic Name The specific name for each Topic Topic Name
Total Conversations The total count of all conversations that have had a Topic during the selected time range. If a Topic was added to a conversation and removed again, within the time range, this Topic will be counted in this metric
Total Current Conversations The count of all conversations that have a Topic at the moment of the export, within the selected time range
Medium The Medium of the Conversation to which the Topic was applied Medium Name
Channel The specific channel of the Conversation to which the Topic was applied Channel Name
Channel Display Name The custom display name of the channel

Tags

All tags that have at least one application in the selected time range.
Header Description Values
Tag ID Unique Identifier for the Tag
Tag Name The name of the Tag Tag Name
Total Contacts The number of Contacts which have had a Tag applied on one of their messages
Total Messages The total number of messages that have had a Tag during the selected time range
Total Current Messages The number of messages that have a Tag applied during the selected time range at the moment of the export
Medium The specific medium from the message on which the Tag has been applied Medium Name
Channel The specific channel from the message on which the Tag has been applied Channel Name
Channel Display Name The custom display name of the channel

User Presence

All users that have at least one away or available time in the selected time range NOTE: If a time range starts or ends out of the selected time frame, it will be included in the report.
Header Description Values
User ID The unique ID for each User
User Name The name of the User User Name
User Email Address The email address of the User Email Address
Type The presence type  Available / Away
Away State Custom away state name 
From Start date Year-Month-Day HH:MM:SS.MS
To End Date Year-Month-Day HH:MM:SS.MS
Duration (s) The duration in which the User has been in this Presence type

Response Times

All responses for which the outbound message was created in the selected time range.
Header Description Values
Conversation ID The unique identifier for each Conversation
Medium The medium on which the Conversation took place Medium Name
Sender Channel The Channel name on which the Contact has contacted you Channel Name
Sender Channel Display Name The custom display name of the channel
Contact Profile ID The unique identifier for each Contact
Started By The reason why the Conversation became visible in the New queue
  • NEW_CONVERSATION
  • VA_HANDED_OVER_CONVERSATION
  • VA_REASSIGNED_CONVERSATION_TO_HUMAN_AGENT 
  •  INBOUND_MESSAGE
Handover Reason In case the “Started by” is “VA_HANDED_OVER_CONVERSATION”, this is the specific reason why there was an Handover
  • MANUALLY_BY_USER
  • USER_DELETED
  • USER_OFFLINE
  • CHANNEL_DELETE,
  • CHANNEL_ACCESS_REVOKED
  • CONVERSATION_RESOLVED
  • VA_ENCOUNTERED_ERROR
  • GDPR_INVOKED
From The timestamp of the “Started By” event. So the actual timestamp which is used to calculate the Response Time HH:MM:SS:MS
To The timestamp of the outbound message HH:MM:SS:MS
Agent Response Time (s) The difference between the “From” and “To”. The time it took an Agent to respond to the contact
Replying Agent ID The unique identifier of the Agent sending the outbound message
Replying Agent Name The name of the Agent send the outbound message
Replying Agent Reference The agent’s internal ID  
Inbound Message ID The unique identifier for the inbound message
Outbound Message ID The unique identifier for the outbound message
Conversation URL The ULR to this conversation in Sparkcentral

Users

This export contains the metrics collected per agent for a selected time range.
Header Description Values
Created At Date and Timestamp of when the user has sent the first outbound message. Year-Month-Day HH:MM:SS.MS
User ID The unique identifier of the user  
User  Name The name of the user User  Name
User Email Address The email address of the user User Email Address
User Reference The internal ID of the user  
Available Time (s) The total time this user has been Available in the selected time range Time in seconds
Away Time (s) The total time this user has been Away in the selected time range Time in seconds
Contacts Handled The number of contacts/customers that received at least 1 inbound from this user
Avg. Handle Time (s) The average of the time the user was  actively working on Conversations (lock) Time in seconds
Handle Time (s) The total time the user actively working on Conversations (lock) Time in seconds
No-Reply Time (s) The total time that the user was looking at Conversations (lock) and resolved it without any reply Time in seconds
Cherry-Picking Time (s) The total time that the user was looking at Conversations (lock) and did not send any reply Time in seconds
Replies The total number of outbound messages sent by this user
Resolves With Reply The total number of conversations which have been resolved by the user and has at least 1 outbound message
Resolves No-Reply The total number of conversations which have been resolved the user without an outbound message
Tags Added The total number of tags added by this user

Contact Attributes

All the contact attributes stored in Sparkcentral, that are either filled out manually by agents, bots, or by retrieving data from a CRM can now be exported. 

Contacts that have messaged your brand in the selected timeframe will be part of the export.

HeaderDescriptionValues
Contact Profile IDUnique Identifier for each Contact/Customer 
Contact Primary IdentifierOne of the two identifiers of the contacts. The value depends on the medium.Name / Phone Number / Alias
Contact Secondary IdentifierOne of the two identifiers of the contacts. The value depends on the medium.Name / Phone Number / Alias
Attribute IDUnique Identifier for each Contact Attribute 
Attribute NameThe name of the Contact Attribute 
Attribute ValueThe value of the defined Contact Attribute 
Attribute TypeThe type of Contact AttributeFreeform / Dropdown

Was this article helpful?

You already voted!

We're always happy to help you ❤️!

Did you know you could help us too?

We love feedback from our users. It’s incredibly important for our business. That’s why a positive recommendation from your company could really make a difference!