File Format Reference
Links between files
sites.csv
One row per social account connected to Alcméon.
Name | Type | Description |
---|---|---|
id | integer | Alcméon id of the social account |
type | string | Social account type. Legal values: business_chat, facebook, gbm, gmb, instagram2, trustpilot, twitter, wechat, webchat, whatsapp, tiktok. |
name | string | Name of social account, as displayed in the Alcméon GUI |
friend_count | deprecated | |
followers_count | deprecated | |
external_id | string | The external identifier coming from the social network API |
alt_external_id | string | An alternative external identifier coming from the social network API |
sitegroups.csv
One row per site_group created in Alcmeon
Name | Type | Description |
---|---|---|
id | integer | A unique stable id associated with this site_group |
name | string | The name of the site group as displayed in the Alcméon user interface |
type | string | The social account type. Legal values: business_chat, facebook, gbm, gmb, instagram2, trustpilot, twitter, wechat, webchat, whatsapp,line, kakaotalk, linkedin, tiktok. |
nb_of_sites_in_group | integer | The number of sites connected to the group |
sites-sitegroups.csv
One row per site created in Alcmeon
Name | Type | Description |
---|---|---|
site_id | integer | A unique stable id associated with this site_group |
group_id | id | A reference to the id column of the sitegroups.csv file. This can be null if the account is not linked to any group |
tags.csv
One row per tag defined in Alcméon.
Name | Type | Description |
---|---|---|
id | integer | A unique stable id for this tag |
is_none | boolean | true if this tag is the default value, false otherwise |
name | string | Name of tag, displayed to Agents |
shortened_name | deprecated | |
category_id | deprecated | |
category_name | deprecated | |
category_group_id | undocumented | |
category_group_name | undocumented |
tasks.csv
One row per message received on one of the social accounts connected within our application.
Name | Type | Description |
---|---|---|
id | integer | A unique stable id associated with this message |
site_id | integer | A reference to the id column of the sites.csv file |
type | string | Type of message received. See below for the list of all types allowed and their meaning. |
tags | string | A list of references to the id column of the tags.csv file, comma-separated. Example: 1,2,5,10 |
message_id | undocumented | |
message_is_deleted | integer | 1 if the message has been deleted by its author within the source social media, 0 otherwise. |
message_content | string | Content of message. On twitter, this field is empty. |
message_parent_id | undocumented | |
message_discussion_id | undocumented | |
message_external_id | string | The native unique id associated with this message within the source social network. |
message_external_url | string | A url where you should be able to view this message in the source social network. |
message_from_id | integer | A unique internal id that identifies the author of this message. |
message_from_name | string | The name of the author of this message. |
message_from_external_id | string | The native unique id associated with the author of this message within the source social network. |
message_from_tw_nfollowers | deprecated | |
message_fb_is_hidden | deprecated | |
message_created_time | string | date/time when this message was written. |
conversation_id | integer | A unique id associated with the conversation this message belongs to. |
rating_value | integer | An integer referring to the rating value given by the user for this message. |
The list of existing message types is documented below.
Channel (tasks.csv:type) | Source social media (sites.csv:type) | Description |
---|---|---|
tw-360 | deprecated | |
tw-@mention | Tweets which @mention your Twitter account. | |
tw-dm | Private messages (aka Direct Messages). | |
fb-pm | Private messages (aka Messenger). | |
fb-user-post | Public posts authored by a customer on your page. | |
fb-news | Public comments by a customer on a publication you authored. | |
fb-ad | Public comments by a customer on an Ad you published (a comment on a Dark Post) | |
fb-event | deprecated | |
fb-rating | A public rating on your page. | |
wc-pm | A message on Wechat | |
instagram-comments | instagram2 | Public instagram comment on a publication you authored |
instagram-live-comments | instagram2 | Public instagram live comments |
instagram-mentions | instagram2 | deprecated |
instagram-private | instagram2 | Private Instagram message (aka Instagram Direct) |
instagram-story-mention | instagram2 | Notification of a user mentioning your account in one of his stories (your answer will be private) |
instagram-story-reply | instagram2 | Notification of a user commenting on of your stories (your answer will be private) |
webchat-msg | webchat | Private message on Alcméon’s WebChat |
gmb-reviews | gmb | Public Google review on one of your locations |
gbm-messages | gbm | Private message on Google Business Message |
whatsapp-msg | Private message on Whatsapp | |
business-chat-msg | business-chat | Private message on Apple Business Chat |
trustpilot-service-review | trustpilot | Public Trustpilot service review |
trustpilot-product-review | trustpilot | Public Trustpilot product review |
kakaotalk-msg | kakaotalk | Private Kakao Talk message |
line-msg | line | Private Line message |
tasks-custom-fields.csv
One row per task. This file is not currently exported. It will be exported sometime during the month of April 2022.
Name | Type | Description |
---|---|---|
task_id | integer | A unique id associated with the task. It references tasks.csv:id |
user_group_id | integer | A unique id associated with the author of the message associated with the task. This id can be used with the GET /custom-fields/users/{user_id} and PUT /custom-fields/users/{user_id} APIs. |
user_group_custom_fields | json | A list of objects with two fields: field_id and field_value, where field_id is an integer and field_value's type depends on the type of the underlying field. Example: [{"field_id": 1, field_value: 23}, {"field_id": 2, field_value: "a string"}] |
conversation_id | integer | A unique id associated with the task's conversation. It references tasks.csv:conversation_id . This id can be used with the GET /custom-field/conversations/{conversation_id} and PUT /custom-field/conversations/{conversation_id} APIs. |
conversation_custom_fields | json | A list of objects with two fields: field_id and field_value, where field_id is an integer and field_value's type depends on the type of the underlying field. Example: `[{"field_id": 1, field_value: 23}, {"field_id": 2, field_value: "a string"}] |
Users and Teams
users.csv
One row per agent.
Name | Type | Description |
---|---|---|
id | integer | A unique id associated with the agent. |
string | The email address used by the agent to login. | |
realname | string | Username, displayed in the Alcméon user interface. |
is_active | integer | 1 if user is active, 0 otherwise. |
is_company_admin | integer | 1 if user is an admin, 0 otherwise. |
nremaining_password_attempts | undocumented | |
lang | string | lang code selected by the agent to translate and localize the Alcméon user interface. |
is_bot | integer | 1 if user is a bot, 0 otherwise. This column does not currently exist. It will be added in November 2022. |
teams.csv
One row per Team.
Name | Type | Description |
---|---|---|
id | integer | A unique id associated with the Team. |
name | string | The name of the team, displayed in the Alcméon user interface |
users-teams.csv
One row for each team a user belongs to.
Name | Type | Description |
---|---|---|
user_id | integer | A reference to the id column of the users.csv file. |
team_id | integer | A reference to the id column of the teams.csv file. |
Actions
actions.csv
One row per action performed by an Agent.
Name | Type | Description |
---|---|---|
id | integer | A unique id associated with the action. |
site_id | integer | A reference to the id column of the sites.csv file. |
type | string | Type of action. All supported values are documented next. |
task_id | integer | A reference to the id column of the tasks.csv file. |
assigned_user_id | integer | A reference to the id column of the users.csv file. This uniquely identifies the user who performed this action. |
assigned_time | undocumented | |
done_time | string | date/time when the Agent performed this action. |
answer_views | undocumented | |
answer_unique_visitors | undocumented | |
in_error | string | "yes" if an error occured while performing this action, "no" ortherwise. |
The list of existing action types is documented below.
Type of action | Description |
---|---|
answered | An answer has been sent to a customer, either by an Agent or a bot. |
archived | A message has been archived, by an Agent or a bot. |
auto-archived | A message has been archived automatically. |
comment | An Agent annotated an incoming message. |
help_request | An Agent requested help from a supervisor |
help_answer | A supervisor replied to a help request |
acquired | An agent acquired (assigned to himself) a message to process it. |
released | An agent moved a message that was assigned to himself back to the received inbox. |
steal | An Agent changed the ownership of a message from another Agent to himself. |
first_seen | An agent opened the for the first time the processing page associated with a message that was assigned to him. |
tag | An agent or a bot has set a tag value on a message. |
execute-answer | Alcméon sent via the social media API an answer after it was logged by an Agent or a Bot via an action of type "answer". |
facebook_like | Social network-specific action |
facebook_unlike | Social network-specific action |
facebook_hide | Social network-specific action |
facebook_unhide | Social network-specific action |
facebook_ban | Social network-specific action |
facebook_unban | Social network-specific action |
facebook_delete | Social network-specific action |
twitter_follow | Social network-specific action |
twitter_unfollow | Social network-specific action |
twitter_block | Social network-specific action |
twitter_unblock | Social network-specific action |
twitter_favorite | Social network-specific action |
twitter_unfavorite | Social network-specific action |
twitter_retweet | Social network-specific action |
twitter_unretweet | Social network-specific action |
twitter_delete | Social network-specific action |
answers.csv
One row per human answer. This file provides more detailed information about an human answer than the actions.csv file.
Name | Type | Description |
---|---|---|
action_id | integer | A reference to the id column of the actions.csv file |
answer_content | string | content of answer |
answer_queued_time | deprecated | |
answer_sent_time | string | date/time when this answer was sent |
answer_retweets | deprecated | |
answer_favorites | deprecated | |
answer_likes | deprecated | |
answer_earned_follows | deprecated | |
answer_npositive_followups | deprecated | |
answer_nnegative_followups | deprecated | |
answer_nneutral_followups | deprecated |
archived.csv
One row per archive action.
Name | Type | Description |
---|---|---|
action_id | integer | A reference to the id column of the actions.csv file |
grouped_from_task_id | undocumented | |
group_id | undocumented | |
group_first_task_id | undocumented | |
group_answer_task_id | undocumented | |
group_size | integer | If empty, a single message was archived. If not empty, the Agent archived mutiple messages with a single click and the content of this column is the number of messages archived. |
annotations.csv
Name | Type | Description |
---|---|---|
action_id | integer | A duplicate of actions.csv:id where type = "comment" |
text | string | The text of the annotation |
help-requests.csv
Name | Type | Description |
---|---|---|
action_id | integer | A duplicate of actions.csv:id where type = "help_request" |
text | string | The text of the help request |
help-request-answers.csv
Name | Type | Description |
---|---|---|
action_id | integer | A duplicate of actions.csv:id where type = "help_answer" |
text | string | The text of the help request answer |
Optins
Optin-related files will be exported after september 1st 2022
optins.csv
One row per optin.
Name | Type | Description |
---|---|---|
id | integer | A unique id for this optin |
name | string | The name of the optin |
type | string | The type of the optin. Valid values are: "default", "recurring-notification-messenger" |
optin-events.csv
One row per optin or optout event.
Name | Type | Description |
---|---|---|
optin_id | integer | A reference to the optins.csv:id column. |
datetime | string | The Date and Time of the event in format YYYY-MM-DD HH:MM:SS in UTC timezone. |
type | string | The type of event. Possible values: "optin", "optout". |
site_id | integer | A reference to the id column of the sites.csv file. |
user_external_id | string | The native id of the user who triggered this event. On Whatsapp, this is a phone number. On Messenger, this is a PSID. etc. |
optout_reason | string | A string indicating why the user was optout |
logins.csv
One row per login or logout event
Name | Type | Description |
---|---|---|
user_id | integer | A reference to the id column of the users.csv file. |
user_name | string | Name of user. Duplicated from users.csv:realname |
user_email | string | Email of user. Duplicated from users.csv:email |
date | string | date/time of event |
action | string | Type of action. Possible values: login, logout. |
KPIs
nps.csv
One row per NPS score assigned by a customer.
Name | Type | Description |
---|---|---|
created_time | string | date/time when the satisfaction survey was sent. |
site_id | integer | A reference to the id column of the sites.csv file. |
task_id | integer | A reference to the id column of the tasks.csv file. |
admin_user_id | integer | A reference to the id column of the users.csv file. |
note_nps | integer | NPS score |
first-human-answer-delays.csv
One row per first answer sent for a message by an Agent.
Name | Type | Description |
---|---|---|
done_time | string | date/time when the answer was sent. |
action_id | integer | A reference to the id column of the actions.csv file. |
task_id | integer | A reference to the id column of the tasks.csv file |
delay_s | integer | Delay calculated as "done_time - tasks.csv:message_created_time" |
bh_delay_s | integer | The same delay as above, excluding the business hours of the team the message was routed to when the agent answered. |
bh_after_tagging_delay_s | integer | Delay calculated as "done_time - time_when_message_was_routed_to_team_who_answered", excluding the business hours of the corresponding team. |
first-human-answer-delay-per-conversation.csv
One row per first answer sent in a conversation by an Agent. Note that first-human-answer-delays.csv and this file differ subtly but significantly: in the former, there will be one entry per first answer per incoming message while in the latter, there will be one entry per conversation.
Name | Type | Description |
---|---|---|
conversation_id | integer | A duplicate of tasks.csv:conversation_id |
done_time | string | A duplicate of actions.csv:done_time |
action_id | integer | A reference to the id column of the actions.csv file. It references the answer action performed by the Agent. |
task_id | integer | A reference to the id column of the tasks.csv file. It references the message the agent replied to. |
delay_s | integer | Delay calculated as "done_time - tasks.csv:message_created_time" |
bh_delay_s | integer | The same delay as above, excluding the business hours of the team the message was routed to when the agent answered. |
bh_after_tagging_delay_s | integer | Delay calculated as "done_time - time_when_message_was_routed_to_team_who_answered", excluding the business hours of the corresponding team. |
Satisfaction surveys
survey_ratings.csv
One row per rating made by a user. Available after October 1st 2023
Name | Type | Description |
---|---|---|
survey_rating_date | string | Date/time the rating was made by the user. |
survey_rating | integer | Survey score given by the user. Contains the label of the button the client clicked on. |
survey_rating_type | integer | Type of the “Feedback” box used in the survey scenario. Can be either “NPS”, “CSAT”, “CES”, “NES” or “Custom” |
survey_rating_type_custom_name | integer | In case of survey_rating_type=”custom”, this is the “name” given in the “Feedback” box. |
survey_rating_message | integer | Message sent to the user that was set up in the “Feedback” box. |
survey_sent_time | string | Date/time when this answer was sentUnique ID of the action of sending the survey |
survey_sent_mode | string | “human” or “bot” |
survey_id | integer | Unique ID of the action of sending the survey |
survey_name | string | The name given to the survey (ie the scenario) created in Alcméon |
site_id | integer | A reference to the id column of the sites.csv file. |
conversation_id | integer | A unique id associated with the conversation this message (the rating) belongs to. Note: this is always empty for a survey sent by a bot scenario. |
task_id | integer | A reference to the id column of the tasks.csv file for the message that triggered the survey Note: this is always empty for a survey sent by a bot scenario. |
message_from_id | integer | A unique internal id that identifies the author of this message that triggered the survey. |
message_from_name | string | The name of the author of this message that triggered the survey. |
message_from_external_id | string | The native unique id associated with the author of this message that triggered the survey within the source social network. |
tags | string | A list of references to the id column of the tags.csv file, comma-separated. Example: 1,2,5,10. Here they are the tags of the message from which the survey was sent. Note: this is always empty for a survey sent by a bot scenario. |
last_user_id_who_answered | integer | A reference to the id column of the users.csv file for the last human agent that answered in the conversation that triggered the survey Note: this is always empty for a survey sent by a bot scenario. |
survey_verbatim.csv
One row per verbatim left by a user. Available after October 1st 2023
Name | Type | Description |
---|---|---|
survey_verbatim_date | string | Date/time when the verbatim was sent. |
survey_verbatim | string | Text message sent as a verbatim by the user. |
survey_verbatim_message | string | Message sent to the user that was set up in the survey scenario and that contains the “user input” exit with “verbatim” checked before the user sent the verbatim. |
survey_sent_time | string | Date/time when this answer was sent |
survey_sent_mode | string | “human” or “bot” |
survey_id | integer | Unique ID of the survey sent (really it is the task_id from which the survey was sent) |
survey_name | string | The name given to the survey (ie the scenario) created in Alcméon |
site_id | integer | A reference to the id column of the sites.csv file. |
conversation_id | integer | A unique id associated with the conversation this message (the rating) belongs to. Note: this is always empty for a survey sent by a bot scenario. |
task_id | integer | A reference to the id column of the tasks.csv file for the message that triggered the survey. Note: this is always empty for a survey sent by a bot scenario. |
message_from_id | integer | A unique internal id that identifies the author of this message that triggered the survey. |
message_from_name | string | The name of the author of this message that triggered the survey. |
message_from_external_id | string | The native unique id associated with the author of this message that triggered the survey within the source social network. |
tags | string | A list of references to the id column of the tags.csv file, comma-separated. Example: 1,2,5,10. Here they are the tags of the message from which the survey was sent. Note: this is always empty for a survey sent by a bot scenario. |
last_user_id_who_answered | integer | A reference to the id column of the users.csv file for the last human agent that answered in the conversation that triggered the survey Note: this is always empty for a survey sent by a bot scenario. |
Updated about 1 month ago