CurlyBytes / BotFramework-FreshDeskChannel

Custom FreshDesk channel for the Bot Framework

Custom FreshDesk channel for the Bot Framework

Initial quick draft. Code can definitely still be optimized.

Goal

• Provide a community-driven custom channel for the Microsoft Bot Framework to allow reading from, and sending responses to, support tickets in the FreshDesk customer service application.

Solution

• The FreshDesk custom channel for Bot Framework is implemented as an Azure function. When called, it checks for any new tickets or new ticket responses, and passes the ticket subject & description along to the Microsoft Bot Framework.
• The custom FreshDesk channel can be invoked in two ways:
  • Via a Timer-based trigger, which will poll the FreshDesk API every x time to fetch new tickets/responses. This method works for most FreshDesk plans that supports API calls.
  • Via a HTTP trigger, which can be configured in specific FreshDesk plans as a webhook that is called when a ticket is updated.
• The FreshDesk channel will use 2 containers on the same CosmosDB instance than the one used by Bot Framework:
  • Freshdesk-botstate-container: Link FreshDesk tickets to conversations happening in the Bot Framework
  • LastRun: Keep track of last execution (only processes differentials to save API limits)

How to set things up

• Install your Bot logic (using BotFramework) on Azure. This should give you following components in Azure: App Service, CosmosDB, StorageAccount, Cognitive services (Luis).
• Add the Direct Line channel to your Bot in Azure. Copy the secret to DirectLineSecret and the name of the bot to BotId in the settings.json.
• Add the CosmosDB CosmosDBEndpointUri, CosmosDBPrimaryKey, CosmosDBDatabaseId, CosmosDBContainerId connection information to the Settings.json.
• Add the FreshDesk FreshDeskClientUrl and FreshDeskAPIKey to the Settings.json.
• Only newly updated tickets after the initial run will be processed, existing tickets will not be handled by Bot Framework.

(Hint: The channel can be easily tested by using the EchoBot sample in Bot Framework Composer)

Current features

• Send bot responses back to customer as a ticket reply. This is the default bot response.

• Add a private note for human engineer, instead of immediate responses to customer (via bot channeldata). To send a private note, and optionally notify an engineer, send following in the ChannelData with the bot message. The email addresses used must be valid agents registered in FreshDesk, otherwise the message will fail.

    {
      "MessageType": "note",
      "Private": true,
      "NotifyEmails": ["[e-mail]", "[e-mail]"]
    }

• Update the ticket status after bot reply. By default the bot will set the status to 'pending' after each reply. To set a different status after the bot response, use following JSON as ChannelData in your bot response. The values to be used correspond to the official FreshDesk API. Updating the ticket state is currently only possible on a 'reply' MessageType.

    {
      "Message": "YourMessage",
      "MessageType": "reply",
      "Status": 4
    }

• Added extensibility for pre-processing of messages before they are sent to the Bot Framework, and post-processing on the bot responses. This allows for extensibility by sending messages through a Logic App connector, Azure Function, or other API integrations and can be used in scenarios such as for example translating bot messages. The extensibility is offered by setting the keys PreProcessingExtensibility and PostProcessingExtensibility in the Settings.json to the URL of your API which should accept the POST method.

  The pre-processing extensibility API will (as an example) receive following object as POST data:

  {
      "TicketId": int,
      "Subject": string,
      "Message": string,
      "Group_id": int,
      "Responder_id": int,
      "Source": int,
      "Company_id": int,
      "Status": int,
      "Product_id": int,
      "Due_by": string,
      "MessageType": string,
      "Private": boolean,
      "RequesterName": string,
      "FromEmail": string,
      "Mobile": string,
      "Phone": string
  }

  The post-processing extensibility API will (as an example) receive the following object as POST data:

  {
    "MessageType": string,
    "Message": string,
    "Private": boolean,
    "NotifyEmails": array of strings,
    "Status": int
  }

Upcoming features

• Allow for delayed bot responses (for example when human confirmation is required before the bot sends a response back)
• Allow conversation termination when either a human agent is assigned, or the ticket status is marked as resolved
• Hand off ticket to human