Twilio resources and metadata documentation.

This documentation describes designed hooks for interaction with Twilio remote resources and abstractions, to clarify how 3rd party messaging processing and persistence layer is going to be integrated into Fuse frontend application.

Twilio Abstractions quick guide.

Abstractions are representations of resources stored on Twilio side, they can be accessible through REST api and SDK (which generally implements its programming interface on top of it). Twilio provides a way to store additional metadata inside of their entities by adding some data into attributes field of an entity.

Twilio Programmable Chat abstractions list:

• Services (full reference)
• Users (full reference)
• Channels (full reference)
• Members (full reference)
• Messages (full reference)
• Roles (full reference)

Service.

A Service is the top-level scope of all other resources in the Programmable Chat REST API. It owns Channels, Users, Messages, Credentials, and all other data for a Chat implementation. In Fuse application each company got its own chat service, with custom unique name equal to company_name's chat service

Use cases/operations.

In Fuse application services are generated on monolith backend, frontend app uses service SID for getting an auth token from chat microservice. Any other interactions with service resources are not required.

Service Metadata.

None.

Users.

The User resource of Programmable Chat represents a particular user represented by an Identity as provided by the developer. In Fuse application identity consists of company_guid_user_id. Users exist within a single Chat Service instance. Users need to be unique (by Identity) within a Service instance. User entities are used to assign permissions via Roles within a Service instance and determine what the user can and cannot do within the instance.

Use cases/operations.

Fuse frontend application does not interact with users resource straightly.

Channels.

The Channel resource of Programmable Chat represents a "chat room" - a scope in which Messages can be sent and received. Members can be added or invited to join channels. Channels exist within a Chat Service scope. A list of a Users Channels can be retrieved which will return all the Channels the specified User is a Member of.

Use cases/operations.

Channels are the main building block for chat application. Almost all interaction happens on channels layer. Fuse app should be able to:

• create a channel
• update a channel, including metadata update (unread messages counters, participant ids, custom name for group chats)
• delete a channel (creators only)
• fetch channel by an authorized user
• add/remove members to channel (creators only)
• leave channel

Channel Metadata.

attributes: {
  custom_name: "example"
  participant_ids: [1, 2, 3],
  unread_messages: {
    1: 5,
    2: 0,
    3: 2
  }
}

• Custom name (String) provides naming by channel creator for chatrooms (for example in group chats)
• Participant ids (Array) stores ids of Fuse users, which are members of chatroom.
• Unread messages (Hash) stores personal unread messages counters for every chatroom member. (keys are built from Fuse user ids, and value is amount of messages that are still were no read by a user, with id equal to key)

Operations description in context of metadata management.

• creating: Channel resource should be created with all attributes provided in example above.
• updating:
  • sending a message (increment all values in unread_messages field, except message author id keyed val)
  • reading a message (decrementing a value in unread_messages with key equal to current user id)
  • adding members (add user id to participant_ids array, add key - value pair to unread_messages field, key = user id, value = 0)
  • removing members (remove user id from participant_ids array, remove key - value pair from unread_messages field)
  • leaving channel (the same as removing members)
  • renaming (change custom_name field)

Members.

The Member resource of Programmable Chat represents the membership of a User within the Service instance to a Channel.

Use cases/operations.

Fuse application should be able to:

• add a member to channel (creators only)
• remove a member from channel (creators only) All these operations are performed via Channel abstraction.

Member metadata.

No additional metatada is stored in Members entity.

Messages.

The Message resource of Programmable Chat represents a single message within a Channel in a Service instance.

Use cases/operations.

• create a message

Hint: Flagging and moderation functionality is not specified because it does not interacting with Twilio.

Message metadata.

attributes: {
  author_id: 3,
  author_name: "Example",
  read: {
    1: false,
    2: false
  }
}

• Author id (Integer) represents Fuse id of messages author
• Author name (String) represents Fuse users name of messages author
• Read (Hash) provides an ability to read messages personally by every chatroom member (keys = participant ids, values = boolean flag, approves or declines a fact of reading by specific user)

Operations description in context of metadata management.

• creating (should be created with all metadata provided in example above, read field should contain all participant ids as key - value pairs, default value is false)
• reading (when the message is being read by a user, a value keyed by this user id should be updated to true)

Roles.

The Role resource of Programmable Chat represents what a user can do within a Chat Service instance.

Use cases/operations.

In Fuse application almost full permissions Twilio roles are used, all permission management happens on Fuse app layer. Fuse frontend application does not directly interact with Roles resource.

Role Metadata.

There is no any metadata on Roles entity.