-
Notifications
You must be signed in to change notification settings - Fork 37
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Update docs for integrating IoGT with RapidPro
- Loading branch information
Showing
1 changed file
with
59 additions
and
30 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,44 +1,73 @@ | ||
| Users can communicate to RapidPro chatbots in IoGT v2. If you are a content creator on an IoGT site, the technical setup on the IoGT server should have been done, and you can set up a chatbot channel. For completeness, the technical setup is outlined at the bottom, but it should not concern content creators. | ||
| Users can communicate with RapidPro chatbots in IoGT v2. | ||
|
|
||
| ## Create a service account in IoGT | ||
|
|
||
| RapidPro needs a service account within IoGT to be able to authenticate itself to IoGT and establish communication. The service account is set up within IoGT as an unprivileged user account within a specific user group. Any Wagtail Admin should be able to set up the service account manually. | ||
|
|
||
| - Create a new group (_Settings_ > _Groups_, _Add a group_) | ||
| - The name must be exactly 'rapidpro_chatbot' | ||
| - No permissions are required | ||
| - Create the service account (_Settings_ > _Users_, _Add a user_) | ||
| - The username just has to be unique | ||
| - Use a long and varied password (no need to remember it) | ||
| - It is recommended to give the user a descriptive first and last name, e.g. 'RapidPro Bot' | ||
| - Add the user to the 'rapidpro_chatbot' group (in the _Roles_ section) | ||
| - Verify everything is set up correctly, by checking that the authorization header to be used by RapidPro when authenticating to IoGT now appears in _Chatbot_ > _Chatbot Channels_. | ||
|
|
||
| You can now set up a channel in RapidPro, and add this channel to IoGT so you can start communicating with it. | ||
|
|
||
| ## Setting up a Chatbot channel | ||
| 1. Find the **Authorization Header Value** for the chatbot on your site by navigating in the Admin Panel to Chatbot > Chatbot Channels. It will be displayed at the top. | ||
| 2. Log in to your workspace on your RapidPro Server. Click Settings > Add Channel | ||
| 3. Select "External Api" | ||
| 1. Find the _Chatbot Authentiation Header_ for the chatbot in the IoGT admin panel at _Chatbot_ > _Chatbot Channels_ - displayed at the top of the page. | ||
| 2. In your workspace in RapidPro, go to _Settings_ > _Add Channel_. | ||
| 3. Select _External Api_. | ||
| 4. Fill in the following form fields | ||
| 1. URN Type: External identifier | ||
| 2. Address: Enter a name identifying your RapidPro server, e.g. my_rapidpro_server | ||
| 3. Method: HTTP POST | ||
| 4. Encoding: Default Encoding (TODO: Confirm this) | ||
| 5. Content type: JSON - application/json | ||
| 6. Max length: `6400` (on older RapidPro installations the upper allowed limit might be only `640`). Note: Messages longer than this size will be split up into multiple parts, and on the IoGT side we have to stitch them back together, which can cause spaces between words to be lost. Thus, the larger this value, the better, so we can avoid messages getting split as much as possible. | ||
| 7. Authorization Header Value: Enter the **Authorization Header Value** from the IoGT Admin Panel > Chatbot > Chatbot Channels mentioned earlier. (Make sure to include the word `Basic` that is displayed, not only the code.) | ||
| 8. Send URL: This should be `https://[URL of the IoGT site]/messaging/api/rapidpro-webhook/` where `[URL of the IoGT site]` is the URL of your IoGT site, e.g. `rw.goodinternet.org`. | ||
| 9. Request Body: `{"id":{{id}}, "text":{{text}}, "to":{{to}}, "to_no_plus":{{to_no_plus}}, "from":{{from}}, "from_no_plus":{{from_no_plus}}, "channel":{{channel}}, "quick_replies":{{quick_replies}}}` (TODO: Check whether we can omit the `to_no_plus` and `from_no_plus`) | ||
| 10. MT Response check: `ok` | ||
| 1. **URN Type**: External identifier | ||
| 2. **Address**: Enter a name identifying your RapidPro server, e.g. my_rapidpro_server | ||
| 3. **Method**: HTTP POST | ||
| 4. **Encoding**: Default Encoding (TODO: Confirm this) | ||
| 5. **Content type**: JSON - application/json | ||
| 6. **Max length**: 6400 (see notes: [1](#note-1), [2](#note-2)) | ||
| 7. **Authorization Header Value**: Enter the _Chatbot Authentiation Header_ from the IoGT admin panel _Chatbot_ > _Chatbot Channels_, mentioned earlier (include the word 'Bearer' as well as the code) | ||
| 8. **Send URL**: `https://[URL of the IoGT site]/messaging/api/rapidpro-webhook/` where `[URL of the IoGT site]` is the URL of your IoGT site, e.g. `rw.goodinternet.org`. | ||
| 9. **Request Body**: `{"id":{{id}}, "text":{{text}}, "to":{{to}}, "to_no_plus":{{to_no_plus}}, "from":{{from}}, "from_no_plus":{{from_no_plus}}, "channel":{{channel}}, "quick_replies":{{quick_replies}}}` (TODO: Check whether we can omit the `to_no_plus` and `from_no_plus`) | ||
| 10. **MT Response check**: ok | ||
| 5. Click _Submit_ | ||
| 6. You will land on a page _External API Configuration_ | ||
| 6. You will land on the _External API Configuration_ page | ||
| 7. Copy the _Received URL_ that is displayed on the page. This URL should look roughly like this: `https://[your RapidPro server]/c/ex/some-uuid-here-7afd839d7123-a95d/receive` | ||
| 8. Go back to the IoGT Admin Panel > Chatbot > Chatbot. Create a new channel. | ||
| 1. DISPLAY NAME: This is the name that users will see when interacting with the bot. | ||
| 2. REQUEST URL: Enter the _Received URL_ from **step 7** here | ||
| 8. Go back to the IoGT admin panel, _Chatbot_ > _Chatbot Channels_, _Create a new channel_. | ||
| 1. **DISPLAY NAME**: This is the name that users will see when interacting with the bot. | ||
| 2. **REQUEST URL**: Enter the _Received URL_ from step 7, immediately above. | ||
|
|
||
| ### Notes | ||
|
|
||
| <a id="note-1">**1**</a> On older RapidPro installations the upper limit might only be up to 640. | ||
|
|
||
| <a id="note-2">**2**</a> Messages longer than the limit will be split up into multiple parts and will have to be re-joined on the IoGT side, which can cause spaces between words to be lost. Thus, larger limits are better, so we can avoid messages being split as much as possible. | ||
|
|
||
| ## Allowing users to interact with a Chatbot | ||
| As part of an article's content, you can now add a _Chatbut button_. It has the following form fields: | ||
| As part of an article's content, you can now add a _Chatbot button_. It has the following form fields: | ||
|
|
||
| 1. Subject: The title identifiying the conversation with the chatbot in the user's inbox. | ||
| 2. Button text: The text to be displayed on the button | ||
| 3. Trigger string: The initial message that will be sent to the chatbot, starting the conversation | ||
| 4. Channel: Select the channel that you just created. | ||
| - **Subject**: The title identifiying the conversation with the chatbot in the user's inbox. | ||
| - **Button text**: The text to be displayed on the button | ||
| - **Trigger string**: The initial message that will be sent to the chatbot, starting the conversation | ||
| - **Channel**: Select the channel you just created. | ||
|
|
||
| Upon clicking the button, the user will be directed to a conversation view with the chatbot. | ||
|
|
||
| The inbox view can be accessed via the URL `https://[URL of the IoGT site]/messaging/inbox/`. To allow users to resume conversations later, you can e.g. create a flat menu entry (Admin Panel > Settings > Flat Menus) linking to this inbox view, or to an article explaining about the chatbot that also has a link to the inbox. | ||
| The inbox view can be accessed via the URL `https://[URL of the IoGT site]/messaging/inbox/`. To allow users to resume conversations later, you can e.g. create a flat menu entry (_Settings_ > _Flat Menus_) linking to this inbox view, or to an article explaining about the chatbot that also has a link to the inbox. | ||
|
|
||
| ## Create a service account in IoGT with the management command | ||
|
|
||
| This is only an option for those who are operating an instance of IoGT (system administrator, ops team). The management commmand performs the manual steps for creating a service account in IoGT (detailed above) and is provided to automate the process (e.g. when an IoGT site is first created). | ||
|
|
||
| ## Technical set up | ||
| The setup command. | ||
| ``` | ||
| python manage.py sync_rapidpro_bot_user | ||
| ``` | ||
|
|
||
| In order to communicate with the IoGT website, RapidPro needs an IoGT user account as which it can authenticate. | ||
| This user needs to be set up on the IoGT side. Once that is done, you can set up a channel on your RapidPro server, | ||
| and add this channel to the IoGT site so you can start communicating with it. | ||
| There is another command that will print the authorization header to be used by RapidPro when authenticating to IoGT. | ||
| ``` | ||
| python manage.py get_rapidpro_authentication_header_value | ||
| ``` | ||
|
|
||
| 1. Run the command `python manage.py sync_rapidpro_bot_user` in django container (to go inside django container run `make ssh`) | ||
| 2. Optional: Run the command `python manage.py get_rapidpro_authentication_header_value` in django container to get the **Authorization Header Value** for RapidPro server. (This value should also be displayed in the admin panel.) | ||
| This is the same value that appears in the IoGT admin panel under _Chatbot_ > _Chatbot channels_. |