Merge branch 'master' of github.com:3sd/civicrm-chatbot

README.md

@@ -11,9 +11,11 @@ A chatbot for CiviCRM. Integrates various chat services (e.g. Facebook messenger
 
 This extension is ***currently in beta***. You are welcome to try it out but be prepared for a couple of bumps along the way. Please report any issues you have using the [github issue tracker](https://github.com/3sd/civicrm-chatbot/issues).
 
+**Note:** this repository also contains [chatbot-civirules](chatbot-civirules) an extension that provides integration between Chatbot with CiviRules. Please ensure that you have CiviRules installed before enabling this extension.
+
 ## Documentation
 
-[Read our WIP documentation here](docs).
+Read the docs at [https://docs.civicrm.org/chatbot](https://docs.civicrm.org/chatbot).
 
 ## Developers
 

docs/chat-activities-and-tab.md

@@ -0,0 +1,9 @@
+# Chat activities and the chat tab
+
+**Incoming chat**, **outgoing chat** and **conversations** are stored in CiviCRM as **activities**. These activities are visible in a contact's **Activity tab** and other places where you normally find activities (e.g. **Activity reports**).
+
+# Chat tab
+
+Conversations that are made up of various activities can be hard to follow amongst all the other activities in the activity tab. For these reason, Chatbot comes with a **Chat tab** where you can see conversations in a more user friendly format.
+
+![Chat tab](chat-tab.png)

docs/civirules-integration.md

@@ -0,0 +1,10 @@
+# CiviRules integration
+
+Chatbot provides a **Start a conversation** action that can be used to start chats based on conditions defined by a CiviRule. This is useful, for example, to start a conversation when someone registers for an event.
+
+Note that for the common use case of starting a conversation when your chatbot hears a certain word (for example when someone says 'help' on your Facebook page), you can use the built in **Hear** functionality for a conversation (note this  s currently only exposed via the UI).
+
+For more complex use cases you should:
+
+1. Define a **CiviRule** with appropriate **conditions** that define the action you want to respond to.
+2. Add a **Start a conversation** action and choose the conversation that you would like to start.

docs/conversation-types.md

@@ -0,0 +1,30 @@
+# Conversation types
+
+**Conversations types** are the main building block of Chatbot. They are made up of a series of **Questions**, for which one can define **actions** to take when various **answers** are received.
+
+View a list of Conversation types by selecting **Chat > Conversation Types** from the menu.
+
+Click the **Add conversation type** button on this screen to create your first conversation type. You will be prompted to name the conversation and enter your first question.
+
+## Questions
+
+Each conversation type consist of a series of questions. Typically the contact will reply to your question with an answer, and you can carry out various **actions** depending on the answer they give you.
+
+## Actions
+
+There are two ways you can reply to someone when they answer you. Ask another question (**Go to Question**), or **Say** to say something without expecting an answer.
+
+Two other actions are currently available:
+
+* Add to group, which allows you to add the contact to a group
+* Add to field, which allows you to record the answer that they have given you in any core or custom contact field.
+
+## Matching
+
+Often, you will only want to carry out an action if the answer matches a certain criteria. For example, if you ask the question "Would you like to be added to our newsletter?", then you would only want to add them to the newsletter if the reply was "Yes" (or something similar).
+
+Matching is configured for each action. You can either choose to match anything, match exact text, or match text containing a phrase.
+
+## Branching
+
+You may want to ask different questions depending on the answer to the previous question. To do this, you configure multiple **Go to question** actions for a question. For example, if we ask someone whether the like Art or Music best, and they reply that they like music the best, we might ask who their favourite band is. But if they say they like Art better, we might ask who their favourite Artist is. For extra bonus points, we could record the answer to the question, what is your favourite band in a custom field called 'Favourite band'.

docs/developer/data-model.md

@@ -1,5 +1,7 @@
 # Data model
 
+***Developer documentation is work in progress - please feel free to contribute***
+
 Chatbot is based on the following data model:
 
 ## New entities

docs/developer/middleware.md

@@ -1,5 +1,7 @@
 # Middleware
 
+***Developer documentation is work in progress - please feel free to contribute***
+
 Chatbot takes advantage of Botman's middleware to build out functionality.
 
 ## Identification

docs/getting-started.md

@@ -0,0 +1,8 @@
+# Getting started
+
+Once you have installed the chatbot extension ([installation instruction here](installation.md)) there are a couple of things you will need to do.
+
+1. [Configure chat services](service/configure.md) for the chat services that you want to use
+2. Define some [conversation types](conversation-types.md) for the different conversations you want to have with your contacts.
+
+Once you've done that, you will be able to [start conversations](starting-conversations.md) with contacts and [monitor chat messages and conversations](chat-and-conversation-tabs.md) in CiviCRM.

docs/index.md

@@ -0,0 +1,15 @@
+# CiviCRM chatbot
+
+CiviCRM chatbot integrates various chat services (like Facebook messenger) with CiviCRM so you can chat with your contacts.
+
+This documentation covers [installation and configuration](installation.md) of the extension, as well as [everyday usage](getting-started.md).
+
+If you get stuck and would like some help, or if you have any other questions, please [get in contact](https://3sd.io/contact) or [file an issue on the github repo](https://github.com/3sd/civicrm-chatbot/issues).
+
+## Credits
+
+Development of the CiviCRM Chatbot extension has been generously funded by the [National Democratic Institute](https://ndi.org).
+
+It is maintained by [Michael McAndrew](https://twitter.com/michaelmcandrew) from [Third Sector Design](https://thirdsectordesign.org/) who you can [contact](https://thirdsectordesign.org/contact) for help, support and further development.
+
+It builds on [Botman.io](https://botman.io/), the excellent PHP chatbot framework by [Marcel Pociot](https://twitter.com/marcelpociot).

docs/installation.md

@@ -0,0 +1,13 @@
+# Installation
+
+Installation for Chatbot is the same as for any other extension.
+
+## Download
+
+Until Chatbot becomes approved for automated download, you will need to manually download it and extract it to your extensions directory.
+
+You can find the latest stable release here: [https://github.com/3sd/civicrm-chatbot/releases](https://github.com/3sd/civicrm-chatbot/releases).
+
+## Install
+
+Once you have downloaded and extracted the extension to your extensions directory, it should appear on the manage extensions page. Enable it and you should be ready to [get started](getting-started.md).

docs/service/civisms.md

@@ -0,0 +1,5 @@
+# CiviSMS configuration
+
+Using Chatbot with CiviSMS (CiviCRM's built in SMS functionality) is quite straight forward.
+
+Ensure that you have [CiviSMS set up](https://docs.civicrm.org/user/en/latest/sms-text-messaging/what-is-sms/) and configured correctly and choose CiviSMS from the list of chat providers.

docs/service/configure.md

@@ -0,0 +1,14 @@
+# Configuring a chat services
+
+Chatbot is built to integrate with multiple chat services. Currently it integrates with CiviCRM's built in SMS service, [CiviSMS](civisms.md) and also with [Facebook messenger](facebook.md).
+
+To use Chatbot with your preferred service, please follow the instructions below:
+
+- [Configure CiviSMS](civisms.md)
+- [Configure Facebook messenger](facebook.md)
+
+Once configured, you can use the chat service to chat with any contacts that have an account with that service.
+
+## Other services
+
+If you would like to use a different chat service, read [integrating with other chat services](other.md).

docs/facebook.md → docs/service/facebook.md

@@ -1,17 +1,14 @@
 # Integrating with Facebook messenger
 
-
 To integrate CiviCRM and Facebook messenger, you will need to:
 
 * create a *Facebook page* where people will chat with you (or use one you have already created)
 * connect your *Facebook page* to a *Facebook app*
 * enter credentials into your *Facebook app* and into *CiviCRM* so they can talk each other.
 
-The following instructions walk you through how to do this.
-
 ## Before you start
 
-Make sure that your CiviCRM site is publicly accessible and served over HTTPS ([Let’s Encrypt](https://letsencrypt.org/) offer the certificates you need for HTTPS for free if you don't already have them).
+Make sure that your CiviCRM site is publicly accessible and served over HTTPS ([Let’s Encrypt](https://letsencrypt.org/) offer free and trustworthy certificates for HTTPS for free if you don't already have one).
 
 ## Set up your Facebook page
 
@@ -44,4 +41,4 @@ Create a *Facebook App* to integrate your free *Facebook Page* with CiviCRM.
   3. Ensure that you are subscribed to *messages*, *message_deliveries*, and *message_reads*.
 8. Click *verify and save*.
 
-If all goes well, your page will be verified and you are ready to start chatting. If the webook does not vefify, make sure that you have followed the above instructions completely. If you are still having issues, [get in contact for some help](../help).
+If all goes well, your page will be verified and you are ready to start chatting. If the webook does not vefify, make sure that you have followed the above instructions completely. If you are still having issues, please [file an issue and someone should be able to help](https://github.com/3sd/civicrm-chatbot/issues).

docs/service/other.md

@@ -0,0 +1,24 @@
+## Integrating with other chat services
+
+It should be reasonably straight forward to add support to any of the following chat services:
+
+- Amazon Alexa
+- Cisco Spark
+- Facebook Messenger
+- Hangouts Chat
+- HipChat
+- Microsoft Bot Framework
+- Nexmo
+- Slack
+- Telegram
+- Twilio
+- Web
+- WeChat
+
+This is because each of these services are supported by Botman.io - the framework upon which Chatbot is built.*
+
+Other chat services could also be supported (by creating a Botman driver for the service) but this would require a bit more work.
+
+Please [file an issue](https://github.com/3sd/civicrm-chatbot/issues) if you would like us to add an integration for a new chat service. Alternatively, if you would like the add the service yourself, we welcome your contribution. Please see the [*Contributing* section of the README](https://github.com/3sd/civicrm-chatbot#contributing) before you start.
+
+\* please see the [Botman documentation](https://botman.io/2.0/) for an up to date list of services that Botman supports.

docs/starting-conversations.md

@@ -0,0 +1,15 @@
+# Starting conversations
+
+Each contact has a  **Chat - start a conversation** action that can be used to start a conversation.
+
+You can also start a conversation with multiple contacts by choosing **Chat - start a conversation** from the actions drop down after any search.
+
+In each case, you will choose the convesation type that you want to have, and the chat service that you want to use for the conversation.
+
+## Starting conversations based on keywords
+
+Chatbot can start conversations automatically when certain phrases are heard. This functionality is not currently exposed via the UI but you can access it via the `ChatHear` API.
+
+## Starting conversations based on other conditions
+
+For more complex scenarios, such as starting a conversation when someone registers for an event, or makes a donation, Chatbot provides a CiviRules action **Start a conversation**. To enable this, you will need to install **CiviRules extension** and the **Chatbot CiviRules** extension.

info.xml

@@ -14,11 +14,11 @@
     <url desc="Support">https://thirdsectordesign.org/chatbot</url>
     <url desc="Licensing">http://www.gnu.org/licenses/agpl-3.0.html</url>
   </urls>
-  <releaseDate>2018-02-08</releaseDate>
-  <version>0.2.0</version>
+  <releaseDate>2018-09-05</releaseDate>
+  <version>1.0.0-beta.1</version>
   <develStage>beta</develStage>
   <compatibility>
-    <ver>5</ver>
+    <ver>5.0</ver>
   </compatibility>
   <civix>
     <namespace>CRM/Chat</namespace>

mkdocs.yml

@@ -0,0 +1,14 @@
+site_name: CiviCRM chatbot
+pages:
+  - Introduction: index.md
+  - Installation: installation.md
+  - Getting started: getting-started.md
+  - Conversation types: conversation-types.md
+  - Starting conversations: starting-conversations.md
+  - Chat and conversation tabs: chat-and-conversation-tabs.md
+  - Chat services:
+    - Configuring a chat service: service/configure.md
+    - CiviSMS: service/civisms.md
+    - Facebook messenger: service/facebook.md
+    - Other services: service/other.md
+  - CiviRules integration: civirules-integration.md