Core entities

Core entities listed here are used in backend-storage and backend-frontend communication. For simplicity reasons, they are all designed to be simple frozen dataclasses. If you are implementing your own Suppgram frontend, you may need to extend these classes with new fields.

Customers

suppgram.entities.Customer dataclass

Describes a particular customer who is interacting with the support system.

Contains the data necessary to identify the external system customer communicates through (e. g. Telegram bot, Instagram business account, PubNub chat, etc.), the data necessary to identify the customer and send them messages within that system, and all available metadata (e.g. first name, last name) that can be useful.

Attributes:
  • id (Any) –

    internal ID of the customer. Type and format may depend on chosen storage.

  • telegram_user_id (Optional[int]) –

    Telegram user ID, if the customer is communicating via a Telegram bot.

  • telegram_first_name (Optional[str]) –

    Telegram user first name, if the customer is communicating via a Telegram bot and has non-empty first name.

  • telegram_last_name (Optional[str]) –

    Telegram user last name, if the customer is communicating via a Telegram bot and has non-empty last name.

  • telegram_username (Optional[str]) –

    Telegram user username, if the customer is communicating via a Telegram bot and their Telegram privacy settings allow access to their username.

  • shell_uuid (Optional[UUID]) –

    UUID of the customer, if the customer is communicating via shell interface.

  • pubnub_user_id (Optional[str]) –

    PubNub user ID, if the customer is communicating via a PubNub channel.

  • pubnub_channel_id (Optional[str]) –

    PubNub channel ID, if the customer is communicating via a PubNub channel.

suppgram.entities.CustomerIdentification dataclass

Subset of Customer fields allowing to uniquely identify the customer.

suppgram.entities.CustomerDiff dataclass

Describes an update to a Customer object.

Is, in fact, a subset of Customer fields representing optional metadata.

Agents

suppgram.entities.Agent dataclass

Describes support agent who is able to communicate with customers via the support system or manage other agents.

Attributes:
  • id (Any) –

    internal ID of the agent. Type and format may depend on chosen storage.

  • telegram_user_id (Optional[int]) –

    Telegram user ID, if the agent is working via Telegram interface.

  • telegram_first_name (Optional[str]) –

    Telegram user first name, if the agent is working via Telegram interface and has non-empty first name.

  • telegram_last_name (Optional[str]) –

    Telegram user last name, if the agent is working via Telegram interface and has non-empty last name.

  • telegram_username (Optional[str]) –

    Telegram user username, if the agent is working via Telegram interface and their Telegram privacy settings allow access to their username.

suppgram.entities.AgentIdentification dataclass

Subset of Agent fields allowing to uniquely identify the agent.

suppgram.entities.AgentDiff dataclass

Describes an update to a Agent object.

Is, in fact, a subset of Agent fields representing optional metadata.

Workplaces

suppgram.entities.Workplace dataclass

Describes support agent's workplace.

Workplace is an abstraction over a way agent conveys their messages. Examples of a workplace include:

  • private Telegram chat with one of the agent bots, identified by user ID and bot ID;
  • PubNub chat, identified by chat ID;
  • web interface session, identified by active websocket identifier.
Attributes:
  • id (Any) –

    internal ID of the workplace. Type and format may depend on chosen storage.

  • agent (Agent) –

    agent the workplace belongs to.

suppgram.entities.WorkplaceIdentification dataclass

Subset of Workplace fields allowing to uniquely identify the workplace.

Conversations

suppgram.entities.Conversation dataclass

Describes a particular conversation between customer and support agent(s).

When a customer sends a message into the support system, a new conversation is created. It can then be assigned to an agent and resolved by them. If the customer sends a message again, previously resolved conversations are ignored and a new one is spawned.

Attributes:
  • id (Any) –

    internal ID of the conversation. Type and format may depend on chosen storage.

  • state (ConversationState) –

    current state of the conversation.

  • customer (Customer) –

    customer who has started the conversation.

  • tags (List[Tag]) –

    list of tags added to the conversation.

  • assigned_agent (Optional[Agent]) –

    agent currently assigned to the conversation.

  • assigned_workplace (Optional[Workplace]) –

    workplace currently assigned to the conversation.

  • messages (List[Message]) –

    list of messages from the beginning of the conversation. Includes customer's messages, agent's messages, and internal messages marking particular events (e.g. conversation resolution).

  • customer_rating (Optional[int]) –

    5-star rating given by the customer after the resolution of the conversation.

suppgram.entities.ConversationDiff dataclass

Describes an update to a Conversation object.

Attributes:
  • state (Optional[ConversationState]) –

    new state of the conversation.

  • assigned_workplace_id (Union[Optional[Any], _SetNone]) –

    ID of the workplace newly assigned to the conversation. Note that workplaces have many-to-one relationship with agents, thus agent ID is not necessary here.

  • added_tags (Optional[List[Tag]]) –

    list of tags to add to the conversation.

  • removed_tags (Optional[List[Tag]]) –

    list of tags to remove from the conversation.

  • customer_rating (Optional[int]) –

    5-star rating newly given by a customer.

suppgram.entities.ConversationState

Bases: str, Enum

Enumeration describing current state of a conversation.

Attributes:
  • NEW –

    newly created conversation waiting for an agent to be assigned

  • ASSIGNED –

    in-progress conversation with an assigned agent

  • RESOLVED –

    conversation resolved by an agent

suppgram.entities.Message dataclass

Describes message within a conversation.

May be a message from customer, agent, or an internal message corresponding to an event (e.g. conversation resolution) depending on kind.

Attributes:
  • kind (MessageKind) –

    message kind.

  • time_utc (datetime) –

    date and time of message creation.

  • text (Optional[str]) –

    message text, if this is a text message.

suppgram.entities.MessageKind

Bases: str, Enum

Enumeration describing message kind.

FROM_CUSTOMER = 'from_customer' class-attribute instance-attribute

Regular message from a customer.

FROM_AGENT = 'from_agent' class-attribute instance-attribute

Regular message from a currently assigned agent.

POSTPONED = 'postponed' class-attribute instance-attribute

Internal message marking the moment the conversation was postponed by the agent.

RESOLVED = 'resolved' class-attribute instance-attribute

Internal message marking the moment the conversation was resolved by the agent.

suppgram.entities.Tag dataclass

Describes tag that can be used to label a conversation.

Attributes:
  • id (Any) –

    internal ID of the tag. Type and format may depend on chosen storage.

  • name (str) –

    tag name.

  • created_at_utc (datetime) –

    date and time when the tag was created.

  • created_by (Agent) –

    agent who has created the tag.