# deltawoot
A deltachat bot which acts as a chatwoot client,
so users can talk to chatwoot encrypted.
## Installation
You need to connect this bot to a working <https://www.chatwoot.com/> instance,
from now on called `example.org`.
Let's configure chatwoot first:
### Configure a callback URL in chatwoot
The bot needs to be reachable via HTTP from the chatwoot instance,
and you need to enter a callback URL into the chatwoot web interface.
For this, go to `https://example.org/app/accounts/1/settings/integrations`
and configure a new webhook.
For example,
If the bot is running on the same docker host as the chatwoot instance,
enter `http://deltawoot.internal:5000` (deltawoot.internal is the container name),
and enable the `message_created` option.
### Add deltawoot to chatwoot's docker-compose.yml
If you installed chatwoot via docker compose
like [here](https://web.archive.org/web/20230601030620/https://www.chatwoot.com/docs/self-hosted/deployment/docker/),
you can add the deltawoot container
to your chatwoot's docker-compose.yml
like this:
```
services:
[...] # here all the chatwoot containers are defined, see https://raw.githubusercontent.com/chatwoot/chatwoot/develop/docker-compose.production.yaml
deltawoot:
image: missytake/deltawoot:latest
restart: unless-stopped
container_name: deltawoot.internal
env_file: /home/chatwoot/.env
depends_on:
- rails
volumes:
- deltawoot:/home/deltawoot/files
ports:
- "127.0.0.1:5000:5000"
volumes:
deltawoot:
```
Then you need to add your environment variables to an `.env` file.
In the example docker-compose.yml above
it is in `/home/chatwoot/.env`,
if you use a different file you should change the path.
It should look like this for example
(more on the meaning of the config parameters below):
```
WOOT_PROFILE_ACCESS_TOKEN=s3cr3t
DELTAWOOT_ADDR=deltawoot@nine.testrun.org
DELTAWOOT_PASSWORD=p4$$w0rD
WOOT_ACCOUNT_ID=1
```
Then you can start the docker container:
```
docker compose up -d
```
### Config Parameters
You can get the `WOOT_PROFILE_ACCESS_TOKEN`
at the bottom of `https://example.org/app/accounts/1/profile/settings`.
Note: after starting chatwoot, you need to give
the account you use to generate the `WOOT_PROFILE_ACCESS_TOKEN`
operator access to the "Deltawoot" API inbox
at `https://example.org/app/accounts/1/settings/inboxes/list`.
For `DELTAWOOT_ADDR`
and `DELTAWOOT_PASSWORD`
you can use any email account.
For the `WOOT_ACCOUNT_ID`,
go to the Chatwoot conversations list
where you want Delta Chat messages to pop up,
e.g. the one which appears directly after logging in.
It should look like `https://example.org/app/accounts/1/dashboard`.
The `WOOT_ACCOUNT_ID` should be the only number in the URL,
in this example `1`, as it is the default.
You might need it if you get a 404 error in the logs
when deltawoot tries to connect to the chatwoot API.
#### Extended Configuration
You can set other environment variables for configuring deltawoot,
for example:
```
WOOT_API_URL=https://example.org/api/v1
DELTAWOOT_NAME=Your friendly Chatwoot Bridge
DELTAWOOT_AVATAR=files/avatar.jpg
DELTAWOOT_HELP_MSG="Hi, ask me for cooking recipes!"
DELTAWOOT_LEAVE_MSG="Please don't add me to groups, write me 1:1 instead."
WOOT_INBOX_ID=1
SENTRY_TOKEN=https://8sahf8dhdufs9fijis9fd@o7898929132132345.ingest.de.sentry.io/3247829357927898
```
`WOOT_API_URL` is only needed
if chatwoot and deltawoot are running on separate hosts;
make sure chatwoot's API URL is reachable from deltawoot's host.
In such a case you also need to reconfigure the callback URL
in chatwoot's Integration settings,
the one we configured in the beginning.
`DELTAWOOT_NAME` will be the bot's display name in Delta Chat.
`DELTAWOOT_AVATAR` will be the bot's avatar in Delta Chat;
if you run deltawoot in docker,
you need to put it into the docker volume,
and prepend the path with `files/`.
`DELTAWOOT_HELP_MSG` is what the bot will say
if you scan it's invite code or
if you send `/help` to it.
You can customize it in your language.
If you try to add the bot to a group,
the bot will leave the group at once,
but send the person who added it an explanation.
`DELTAWOOT_LEAVE_MSG` is what the bot says
in such a situation.
By default, deltawoot creates an API channel itself.
But if you want to use an existing API channel,
you can manually set the `WOOT_INBOX_ID`.
Go to the settings of the API channel you want to use
at `example.org/app/accounts/1/settings/inboxes/list`,
click on the Settings,
look at the number at the end of the URL,
and add it as `WOOT_INBOX_ID`.
If you want to monitor deltawoot errors with <https://sentry.io>,
you can specify a `SENTRY_TOKEN` as environment variable.
### Add Agents to the Delta Chat Inbox
Now you have to add some agents to your Inbox,
so they can actually read the messages
incoming via Delta Chat.
For this, go to `https://example.org/app/accounts/1/settings/inboxes/list`
and next to "Delta Chat",
click on the settings wheel.
Then click on "Collaborators",
add all agents you want to handle the incoming requests,
and finally click on "Update".
### Publish the Invite Link for Your Bot
Now you can look into the logs
with `docker logs -ft deltawoot.internal`,
to find out the join code of the bot:
```
2024-07-10T14:20:22.427084078Z INFO:root:Running deltachat core v1.141.2
2024-07-10T14:20:22.820477302Z INFO:root:New chatwoot inbox created for deltawoot, please add agents to it here: https://example.org/app/accounts/1/settings/inboxes/1
2024-07-10T14:20:22.431288436Z You can publish this invite code to your users: OPENPGP4FPR:AA5FDEF02BFC355FDEA09FF4CA4AFCD2F065E613#a=deltawoot%40nine.testrun.org&n=deltawoot%40nine.testrun.org&i=q4DhTVr1T2A&s=mT3Bo9JDdVx
2024-07-10T14:20:22.437551296Z * Serving Flask app 'deltawoot-webhook'
2024-07-10T14:20:22.438395066Z * Debug mode: on
2024-07-10T14:20:22.451052630Z INFO:root:src/securejoin.rs:126: Generated QR code.
2024-07-10T14:20:22.451080018Z INFO:root:src/scheduler.rs:66: starting IO
```
Copy-paste the `OPENPGP4FPR:` and everything behind it
into the form at <https://i.delta.chat>
to generate an invite link which you can advertise on your contact page.
## Development
If you want to develop without docker,
you can configure and start deltawoot like this:
```
python3 -m venv venv
. venv/bin/activate
pip install -e .[dev]
export WOOT_URL=https://example.org/api/v1
export WOOT_PROFILE_ACCESS_TOKEN=s3cr3t
export WOOT_ACCOUNT_ID=1
export DELTAWOOT_ADDR=deltawoot@nine.testrun.org
export DELTAWOOT_PASSWORD=p4$$w0rD
deltawoot
```
You can run the tests with `pytest`.
## Release Checklist
- [ ] `git checkout -b prepare-1.x.x`
- [ ] Update version number in changelog
- [ ] Update version number in setup.cfg
- [ ] `git commit -am "prepare 1.x.x release"`
- [ ] `git tag 1.x.x`
- [ ] `git push --tags -u origin prepare-1.x.x`
- [ ] open a PR, copy this checklist there
- [ ] `python -m build`
- [ ] `twine check dist/*`
- [ ] `twine upload dist/*`
- [ ] `sudo docker build -t missytake/deltawoot .`
- [ ] `sudo docker tag missytake/deltawoot missytake/deltawoot:1.x.x`
- [ ] `sudo docker push missytake/deltawoot:1.x.x`
- [ ] `sudo docker push missytake/deltawoot:latest`
- [ ] merge this PR and make a github release
Raw data
{
"_id": null,
"home_page": "https://github.com/deltachat-bot/deltawoot",
"name": "deltawoot",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": "missytake",
"author_email": "missytake@systemli.org",
"download_url": "https://files.pythonhosted.org/packages/6c/da/b69cd62916fc212425dd0010afdb24b5e30a364c32280ad1e32273cebc9d/deltawoot-1.3.1.tar.gz",
"platform": null,
"description": "# deltawoot\n\nA deltachat bot which acts as a chatwoot client,\nso users can talk to chatwoot encrypted.\n\n\n## Installation\n\nYou need to connect this bot to a working <https://www.chatwoot.com/> instance,\nfrom now on called `example.org`.\nLet's configure chatwoot first:\n\n\n### Configure a callback URL in chatwoot\n\nThe bot needs to be reachable via HTTP from the chatwoot instance,\nand you need to enter a callback URL into the chatwoot web interface.\nFor this, go to `https://example.org/app/accounts/1/settings/integrations`\nand configure a new webhook.\n\nFor example,\nIf the bot is running on the same docker host as the chatwoot instance,\nenter `http://deltawoot.internal:5000` (deltawoot.internal is the container name),\nand enable the `message_created` option.\n\n\n### Add deltawoot to chatwoot's docker-compose.yml\n\nIf you installed chatwoot via docker compose\nlike [here](https://web.archive.org/web/20230601030620/https://www.chatwoot.com/docs/self-hosted/deployment/docker/),\nyou can add the deltawoot container\nto your chatwoot's docker-compose.yml\nlike this:\n\n```\nservices:\n [...] # here all the chatwoot containers are defined, see https://raw.githubusercontent.com/chatwoot/chatwoot/develop/docker-compose.production.yaml\n deltawoot:\n image: missytake/deltawoot:latest\n restart: unless-stopped\n container_name: deltawoot.internal\n env_file: /home/chatwoot/.env\n depends_on:\n - rails\n volumes:\n - deltawoot:/home/deltawoot/files\n ports:\n - \"127.0.0.1:5000:5000\"\nvolumes:\n deltawoot:\n```\n\nThen you need to add your environment variables to an `.env` file.\nIn the example docker-compose.yml above\nit is in `/home/chatwoot/.env`,\nif you use a different file you should change the path.\nIt should look like this for example\n(more on the meaning of the config parameters below):\n\n```\nWOOT_PROFILE_ACCESS_TOKEN=s3cr3t\nDELTAWOOT_ADDR=deltawoot@nine.testrun.org\nDELTAWOOT_PASSWORD=p4$$w0rD\nWOOT_ACCOUNT_ID=1\n```\n\nThen you can start the docker container:\n\n```\ndocker compose up -d\n```\n\n\n### Config Parameters\n\nYou can get the `WOOT_PROFILE_ACCESS_TOKEN`\nat the bottom of `https://example.org/app/accounts/1/profile/settings`.\nNote: after starting chatwoot, you need to give\nthe account you use to generate the `WOOT_PROFILE_ACCESS_TOKEN`\noperator access to the \"Deltawoot\" API inbox\nat `https://example.org/app/accounts/1/settings/inboxes/list`.\n\nFor `DELTAWOOT_ADDR`\nand `DELTAWOOT_PASSWORD`\nyou can use any email account.\n\nFor the `WOOT_ACCOUNT_ID`,\ngo to the Chatwoot conversations list\nwhere you want Delta Chat messages to pop up,\ne.g. the one which appears directly after logging in.\nIt should look like `https://example.org/app/accounts/1/dashboard`.\nThe `WOOT_ACCOUNT_ID` should be the only number in the URL,\nin this example `1`, as it is the default.\nYou might need it if you get a 404 error in the logs\nwhen deltawoot tries to connect to the chatwoot API.\n\n\n#### Extended Configuration\n\nYou can set other environment variables for configuring deltawoot,\nfor example:\n\n```\nWOOT_API_URL=https://example.org/api/v1\nDELTAWOOT_NAME=Your friendly Chatwoot Bridge\nDELTAWOOT_AVATAR=files/avatar.jpg\nDELTAWOOT_HELP_MSG=\"Hi, ask me for cooking recipes!\"\nDELTAWOOT_LEAVE_MSG=\"Please don't add me to groups, write me 1:1 instead.\"\nWOOT_INBOX_ID=1\nSENTRY_TOKEN=https://8sahf8dhdufs9fijis9fd@o7898929132132345.ingest.de.sentry.io/3247829357927898\n```\n\n`WOOT_API_URL` is only needed\nif chatwoot and deltawoot are running on separate hosts;\nmake sure chatwoot's API URL is reachable from deltawoot's host.\nIn such a case you also need to reconfigure the callback URL\nin chatwoot's Integration settings,\nthe one we configured in the beginning.\n\n`DELTAWOOT_NAME` will be the bot's display name in Delta Chat.\n\n`DELTAWOOT_AVATAR` will be the bot's avatar in Delta Chat;\nif you run deltawoot in docker,\nyou need to put it into the docker volume,\nand prepend the path with `files/`.\n\n`DELTAWOOT_HELP_MSG` is what the bot will say\nif you scan it's invite code or\nif you send `/help` to it.\nYou can customize it in your language.\n\nIf you try to add the bot to a group,\nthe bot will leave the group at once,\nbut send the person who added it an explanation.\n`DELTAWOOT_LEAVE_MSG` is what the bot says\nin such a situation.\n\nBy default, deltawoot creates an API channel itself.\nBut if you want to use an existing API channel,\nyou can manually set the `WOOT_INBOX_ID`.\nGo to the settings of the API channel you want to use\nat `example.org/app/accounts/1/settings/inboxes/list`,\nclick on the Settings,\nlook at the number at the end of the URL,\nand add it as `WOOT_INBOX_ID`.\n\nIf you want to monitor deltawoot errors with <https://sentry.io>,\nyou can specify a `SENTRY_TOKEN` as environment variable.\n\n\n### Add Agents to the Delta Chat Inbox\n\nNow you have to add some agents to your Inbox,\nso they can actually read the messages\nincoming via Delta Chat.\n\nFor this, go to `https://example.org/app/accounts/1/settings/inboxes/list`\nand next to \"Delta Chat\",\nclick on the settings wheel.\nThen click on \"Collaborators\",\nadd all agents you want to handle the incoming requests,\nand finally click on \"Update\".\n\n\n### Publish the Invite Link for Your Bot\n\nNow you can look into the logs\nwith `docker logs -ft deltawoot.internal`,\nto find out the join code of the bot:\n\n```\n2024-07-10T14:20:22.427084078Z INFO:root:Running deltachat core v1.141.2\n2024-07-10T14:20:22.820477302Z INFO:root:New chatwoot inbox created for deltawoot, please add agents to it here: https://example.org/app/accounts/1/settings/inboxes/1\n2024-07-10T14:20:22.431288436Z You can publish this invite code to your users: OPENPGP4FPR:AA5FDEF02BFC355FDEA09FF4CA4AFCD2F065E613#a=deltawoot%40nine.testrun.org&n=deltawoot%40nine.testrun.org&i=q4DhTVr1T2A&s=mT3Bo9JDdVx\n2024-07-10T14:20:22.437551296Z * Serving Flask app 'deltawoot-webhook'\n2024-07-10T14:20:22.438395066Z * Debug mode: on\n2024-07-10T14:20:22.451052630Z INFO:root:src/securejoin.rs:126: Generated QR code.\n2024-07-10T14:20:22.451080018Z INFO:root:src/scheduler.rs:66: starting IO\n```\n\nCopy-paste the `OPENPGP4FPR:` and everything behind it\ninto the form at <https://i.delta.chat>\nto generate an invite link which you can advertise on your contact page.\n\n## Development\n\nIf you want to develop without docker,\nyou can configure and start deltawoot like this:\n\n```\npython3 -m venv venv\n. venv/bin/activate\npip install -e .[dev]\nexport WOOT_URL=https://example.org/api/v1\nexport WOOT_PROFILE_ACCESS_TOKEN=s3cr3t\nexport WOOT_ACCOUNT_ID=1\nexport DELTAWOOT_ADDR=deltawoot@nine.testrun.org\nexport DELTAWOOT_PASSWORD=p4$$w0rD\ndeltawoot\n```\n\nYou can run the tests with `pytest`.\n\n## Release Checklist\n\n- [ ] `git checkout -b prepare-1.x.x`\n- [ ] Update version number in changelog\n- [ ] Update version number in setup.cfg\n- [ ] `git commit -am \"prepare 1.x.x release\"`\n- [ ] `git tag 1.x.x`\n- [ ] `git push --tags -u origin prepare-1.x.x`\n- [ ] open a PR, copy this checklist there\n- [ ] `python -m build`\n- [ ] `twine check dist/*`\n- [ ] `twine upload dist/*`\n- [ ] `sudo docker build -t missytake/deltawoot .`\n- [ ] `sudo docker tag missytake/deltawoot missytake/deltawoot:1.x.x`\n- [ ] `sudo docker push missytake/deltawoot:1.x.x`\n- [ ] `sudo docker push missytake/deltawoot:latest`\n- [ ] merge this PR and make a github release\n\n",
"bugtrack_url": null,
"license": null,
"summary": "A deltachat client for chatwoot, so users can talk to chatwoot encrypted.",
"version": "1.3.1",
"project_urls": {
"Bug Tracker": "https://github.com/deltachat-bot/deltawoot/issues",
"Homepage": "https://github.com/deltachat-bot/deltawoot"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "28be52d6396de73cac86bd81b9673e1829fbaac05ef45f8129fae364f448f0d7",
"md5": "59af6a29dcfd6523e2a74b87615afd68",
"sha256": "bc4a176a29df257ebf37ef83d23f31899734eda8bb25a2d0486538d339af04b1"
},
"downloads": -1,
"filename": "deltawoot-1.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "59af6a29dcfd6523e2a74b87615afd68",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 44186,
"upload_time": "2024-08-18T10:59:35",
"upload_time_iso_8601": "2024-08-18T10:59:35.191219Z",
"url": "https://files.pythonhosted.org/packages/28/be/52d6396de73cac86bd81b9673e1829fbaac05ef45f8129fae364f448f0d7/deltawoot-1.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6cdab69cd62916fc212425dd0010afdb24b5e30a364c32280ad1e32273cebc9d",
"md5": "8393157cb3a489b3450eb0c3736a3e1b",
"sha256": "6750b1628bdc4addb6a229ba3c33918b97e75db4a2141cbb2c803098965232d0"
},
"downloads": -1,
"filename": "deltawoot-1.3.1.tar.gz",
"has_sig": false,
"md5_digest": "8393157cb3a489b3450eb0c3736a3e1b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 52653,
"upload_time": "2024-08-18T10:59:37",
"upload_time_iso_8601": "2024-08-18T10:59:37.493965Z",
"url": "https://files.pythonhosted.org/packages/6c/da/b69cd62916fc212425dd0010afdb24b5e30a364c32280ad1e32273cebc9d/deltawoot-1.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-18 10:59:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "deltachat-bot",
"github_project": "deltawoot",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "deltawoot"
}
JSON
