Skip to content

Commit

Permalink
docs: update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@serfreeman1337
serfreeman1337 committed Jul 14, 2023
1 parent 5d6cc65 commit 4dd6d5f
Show file tree
Hide file tree
Showing 5 changed files with 223 additions and 86 deletions.
44 changes: 22 additions & 22 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,13 @@ Supports FreePBX v14 integration with [Bitrix24](https://github.com/serfreeman13

# Asterisk
You need Asterisk 13+.
To monitor how call is going this connector listens for AMI events.
To monitor calls this connector listens for AMI events.

There should be 4 **different** contexts to distinguish calls:
* `incoming_context` - context for incoming calls from voip trunk. inbound calls will be registred there
* `outgoing_context` - context for outgoing calls. outbound calls will be registred there
* `ext_context` - extensions dials from queue, ring group, etc. use this context to route incoming calls to your extensions
* `dial_context` - context for originating (click2dial) calls
* `incoming_context` - context for incoming calls from voip trunk. inbound calls will be registred there.
* `outgoing_context` - context for outgoing calls. outbound calls will be registred there.
* `ext_context` - extensions dials from queue, ring group, etc. use this context to route incoming calls to your extensions.
* `dial_context` - context for originating (click2dial) calls.

Default configuration is tested to work with FreePBX v14 and Asterisk v13.

Expand All @@ -32,50 +32,50 @@ You see `DCS-Incoming` in `ext_context` because we are dialing **queue** extensi
## CallerID Format
Connector can format CallerID using regexp. This useful when your VoIP provider doesn't send desired format.

* `cid_format` - from PBX to CRM
* `dial_format` - from CRM to PBX
* `expr` - regual expression (use double blackslashes)
* `repl` - replace pattern
* `cid_format` - from PBX to CRM.
* `dial_format` - from CRM to PBX.
* `expr` - regual expression (use double blackslashes).
* `repl` - replace pattern.

If config is set and callerid doesn't matched any of regexp, then call will be ignored.

# CRM Integration
See instructions in the following files:
* [README_bitrix24.md](https://github.com/serfreeman1337/asterlink/blob/master/README_bitrix24.md) - For [Bitrix24](https://www.bitrix24.com/) Integration
* [README_suitecrm.md](https://github.com/serfreeman1337/asterlink/blob/master/README_suitecrm.md) - For [SuiteCRM](https://suitecrm.com/) Integration
* [README_bitrix24.md](https://github.com/serfreeman1337/asterlink/blob/master/README_bitrix24.md) - For [Bitrix24](https://www.bitrix24.com/) Integration.
* [README_suitecrm.md](https://github.com/serfreeman1337/asterlink/blob/master/README_suitecrm.md) - For [SuiteCRM](https://suitecrm.com/) Integration.

# Install
Install asterlink under **/opt/asterlink** folder.
* Create folder /opt/asterlink
* Create folder /opt/asterlink:
```bash
mkdir /opt/asterlink; cd /opt/asterlink
```
* Download binary from releases page
* Download binary from releases page:
```bash
wget https://github.com/serfreeman1337/asterlink/releases/latest/download/asterlink_x86_64.tar.gz
tar xvf asterlink_x86_64.tar.gz && rm asterlink_x86_64.tar.gz
chmod +x asterlink
```
* Or build it from source (assume you have go installed)
```bash
go get github.com/serfreeman1337/asterlink
go build github.com/serfreeman1337/asterlink
```
* Create configuration file. Use conf.example.yml as example.
* Or build it from source (assume you have [go installed](https://go.dev/doc/install)):
```bash
go get github.com/serfreeman1337/asterlink
go build github.com/serfreeman1337/asterlink
```
* Create configuration file. Use `conf.example.yml` as an example.
```bash
wget https://raw.githubusercontent.com/serfreeman1337/asterlink/master/conf.example.yml
mv conf.example.yml conf.yml
nano conf.yml
```
Note: config file is using YAML format and <ins>it requires to have proper indentation</ins>.
**Note:** config file is using YAML format and <ins>it requires to have proper indentation</ins>.
Use online yaml validator to check your file for errors.
* Test run
* Test run:
```bash
./asterlink
```

## Startup script example
Create **/etc/systemd/system/asterlink.service** file with following contents:
Create `/etc/systemd/system/asterlink.service` file with following contents:
```
[Unit]
Description=AsterLink Connector
Expand Down
30 changes: 16 additions & 14 deletions README_bitrix24.md
View file
Original file line number Diff line number Diff line change
@@ -1,19 +1,21 @@
# Asterlink Bitrix24 Integration
# Asterisk Bitrix24 Integration

## Basic setup
* Bitrix24 -> Applications -> Webhooks -> Add inbound webhook
* Access permissions - check **crm**, **telephony**, **user**
* Copy "**REST call example URL**" ***without*** "*profile/*" to **webhook_url** in config
* Bitrix24 -> Telephony -> Configure telephony -> Telephony users
* Configure extensions for users
## Call originations from Bitrix24
* Configure **webhook_endpoint_addr** in config
* [Install and configure asterlink service](https://github.com/serfreeman1337/asterlink/blob/master/README.md) first.
* Uncomment `b24` entry in `conf.yml` file.
* Bitrix24 -> Applications -> Developer resources -> Other -> Add inbound webhook:
* Access permissions - check **crm**, **telephony**, **user**.
* Copy "**REST call example URL**" ***without*** "*profile/*" to **webhook_url** in config.
* Bitrix24 -> Telephony (open /telephony address) -> Configure telephony -> Telephony users:
* Configure extensions for users.
## Call originations from Bitrix24
* Configure **webhook_endpoint_addr** in `conf.yml`.
* Bitrix24 -> Applications -> Webhooks -> Add outbound webhook
* Handler address - **http://my_endpoint_addr/originate/**
* Event type - **ONEXTERNALCALLSTART**
* Copy "**Authentication code**" to **webhook_originate_token** in config
* Bitrix24 -> Telephony -> Configure telephony -> Telephony settings
* Default number for outgoing calls - Select your outbound hook
* Handler address - **http://my_endpoint_addr/originate/**.
* Event type - **ONEXTERNALCALLSTART**.
* Copy "**Authentication code**" to **webhook_originate_token** in `conf.yml`.
* Bitrix24 -> Telephony -> Configure telephony -> Telephony settings.
* Default number for outgoing calls - Select your outbound hook.
## Forwarding calls to assigned user
Dialplan example:
```
Expand All @@ -29,7 +31,7 @@ Bitrix24 can download and store call recording.
```
ln -s /var/spool/asterisk/monitor /var/www/html/recfiles
```
* Set **rec_upload** url in config
* Set **rec_upload** url in config:
```
http://my_pbx_addr/recfiles/
```
197 changes: 166 additions & 31 deletions README_suitecrm.md
View file
Original file line number Diff line number Diff line change
@@ -1,42 +1,173 @@
# AsterLink SuiteCRM Integration
# Asterisk SuiteCRM Integration
Features:
* Calls logging.
* Dialing for "tel" fields.
* Click-2-Call for phone fields.
* Pop up card for incoming and outgoing calls.
* Forwarding calls to assigned user.

## Basic setup
* Download [suitecrm-asterlink-module.zip](https://github.com/serfreeman1337/asterlink/releases/latest/download/suitecrm-asterlink-module.zip) archive from the releases page.
Or create this archive by your own from the contents of the [connect/suitecrm/suitecrm-asterlink-module](https://github.com/serfreeman1337/asterlink/tree/master/connect/suitecrm/suitecrm-asterlink-module) folder.
* Upload and install this module on the **Module Loader** SuiteCRM Administrator page.
* Configure `Token` on the **AsterLink Settings** SuiteCRM Administrator page.
Token must be equal with the one in **conf.yml** file.
## Install
**For SuiteCRM 8 minimum working version is 8.2.0!**
* [Install and configure asterlink service](https://github.com/serfreeman1337/asterlink/blob/master/README.md) first.
* Uncomment `suitecrm` entry in `conf.yml` file and set:
* `url` - SuiteCRM site address.
* `endpoint_token` - any reasonable value.
* `endpoint_addr` - listen address of the asterlink service.
**Note:** config file is using YAML format and it requires to have proper indentation.
Use online yaml validator to check your file for errors.
* Download [suitecrm-asterlink-module.zip](https://github.com/serfreeman1337/asterlink/releases/latest/download/suitecrm-asterlink-module.zip) archive from the [releases page](https://github.com/serfreeman1337/asterlink/releases).
**SuiteCRM 8:** Extension in the module archive was built with the `8.2.0` version and tested to work with the `8.3.1`.
* Upload and install this module using **Module Loader** on the SuiteCRM Admin page.
* On the SuiteCRM Admin page open **AsterLink Connector** module settings and set:
* `Token` - to `endpoint_token` value in the `conf.yml` file.
* `Endpoint URL` - AsterLink service address (AsterLink uses http protocol, so it must start with `http://`).
**Note:** AsterLink service address must be reachable for users browsers or if you `Enable proxy`, for SuiteCRM site only.
* Optional: display seconds for call duration in detail view:
Click `Add seconds to call duration view field` on the **AsterLink Settings** SuiteCRM Administrator page.
* Update layouts as you want.
* Set `Asterisk Extensions` in users profiles.
* Do a test run of asterlink app. You should see userids from suitecrm in console.
Click `Add seconds to call duration view field`.
* Set `Asterisk Extensions` for users (edit user profile).
* Do a test run of asterlink service. You should see userids from suitecrm in the console.
**Note:** You need to restart the asterlink app evertime you change asterisk extensions for users.

Note: You need to restart asterlink app evertime you change asterisk extensions for users.
**SuiteCRM 8:** If anything go wrong, simply delete `/extensions/asterlink` and `/cache` folders.

## Click-to-Call and Pop up card
* Configure `endpoint_addr` in the **conf.yml** file.
* Configure `Endpoint URL` for Click-to-Call function and `WebSocket URL` for pop up card on the **AsterLink Settings** SuiteCRM Administrator page.
* Check `Enable click-to-call for phone numbers Information` on the SuiteCRM System Settings page.
Note: SuiteCRM will only enable this for CallerID with begining plus sign.

### Apache2 endpoint proxy
* Enable mod_proxy, mod_proxy_http and mod_proxy_wstunnel.
* Config:
```
ProxyPass "/asterlink/ws/" "ws://my_endpoint_addr:my_endpoint_port/ws/"
ProxyPass "/asterlink/" "http://my_endpoint_addr:my_endpoint_port/"
```
* Update AsterLink module settings:
```
Endpoint URL: http://my_endpoint_addr:my_endpoint_port/
WebSocket URL: ws://my_endpoint_addr:my_endpoint_port/ws/
```
<details>
<summary>
SuiteCRM 8 extension build
</summary>

* Append following to `projects` entry in `angular.json` configuration:
```
"asterlink": {
"projectType": "application",
"schematics": {
"@schematics/angular:component": {
"style": "css"
},
"@schematics/angular:application": {
"strict": true
}
},
"root": "extensions/asterlink/app",
"sourceRoot": "extensions/asterlink/app/src",
"prefix": "app",
"architect": {
"build": {
"builder": "ngx-build-plus:browser",
"options": {
"outputPath": "extensions/asterlink/Resources/public",
"index": "extensions/asterlink/app/src/index.html",
"main": "extensions/asterlink/app/src/main.ts",
"polyfills": "extensions/asterlink/app/src/polyfills.ts",
"tsConfig": "extensions/asterlink/app/tsconfig.app.json",
"inlineStyleLanguage": "css",
"assets": [
"extensions/asterlink/app/src/favicon.ico",
"extensions/asterlink/app/src/assets"
],
"styles": [
"extensions/asterlink/app/src/styles.css"
],
"scripts": [],
"extraWebpackConfig": "extensions/asterlink/app/webpack.config.js",
"commonChunk": false,
"namedChunks": true,
"sourceMap": true,
"aot": true
},
"configurations": {
"production": {
"budgets": [
{
"type": "initial",
"maximumWarning": "2mb",
"maximumError": "5mb"
},
{
"type": "anyComponentStyle",
"maximumWarning": "6kb",
"maximumError": "10kb"
}
],
"fileReplacements": [
{
"replace": "extensions/asterlink/app/src/environments/environment.ts",
"with": "extensions/asterlink/app/src/environments/environment.prod.ts"
}
],
"outputHashing": "all",
"extraWebpackConfig": "extensions/asterlink/app/webpack.prod.config.js",
"optimization": true,
"sourceMap": false,
"namedChunks": true,
"extractLicenses": true,
"vendorChunk": false,
"buildOptimizer": true
},
"dev": {
"buildOptimizer": false,
"optimization": false,
"vendorChunk": false,
"extractLicenses": false,
"sourceMap": true,
"outputPath": "public/extensions/asterlink"
}
},
"defaultConfiguration": "production"
},
"serve": {
"builder": "ngx-build-plus:dev-server",
"configurations": {
"production": {
"browserTarget": "asterlink:build:production",
"extraWebpackConfig": "extensions/asterlink/app/webpack.prod.config.js"
},
"development": {
"browserTarget": "asterlink:build:development"
}
},
"defaultConfiguration": "development",
"options": {
"port": 34000,
"extraWebpackConfig": "extensions/asterlink/app/webpack.config.js"
}
},
"extract-i18n": {
"builder": "ngx-build-plus:extract-i18n",
"options": {
"browserTarget": "asterlink:build",
"extraWebpackConfig": "extensions/asterlink/app/webpack.config.js"
}
},
"test": {
"builder": "@angular-devkit/build-angular:karma",
"options": {
"main": "extensions/asterlink/app/src/test.ts",
"polyfills": "extensions/asterlink/app/src/polyfills.ts",
"tsConfig": "extensions/asterlink/app/tsconfig.spec.json",
"karmaConfig": "extensions/asterlink/app/karma.conf.js",
"inlineStyleLanguage": "css",
"assets": [
"extensions/asterlink/app/src/favicon.ico",
"extensions/asterlink/app/src/assets"
],
"styles": [
"extensions/asterlink/app/src/styles.css"
],
"scripts": []
}
}
}
}
```
* Append following to `scripts` in `package.json` configuration:
```
"run:all": "node node_modules/@angular-architects/module-federation/src/server/mf-dev-server.js",
"build-dev:asterlink": "ng build asterlink --configuration dev",
"build:asterlink": "ng build asterlink --configuration production"
```
* Follow [Front-end Developer Install Guide](https://docs.suitecrm.com/8.x/developer/installation-guide/front-end-installation-guide/).
* Run `yarn run build:asterlink` to build extension.
* More info: [Setting Up a Front-End Extension Module](https://docs.suitecrm.com/8.x/developer/extensions/frontend/fe-extensions-setup/)
</details>
## Forwarding calls to assigned user
Dialplan example:
Expand All @@ -48,6 +179,10 @@ same => n,Goto(ext-queues,400,1)
same => n,Hangup
```
## Upgrade from 0.4 version
* Just upload new module. SuiteCRM should handle upgrading.
* You might need to run "Quick Repair and Rebuild".
## Upgrade from 0.3 version
* Its highly recomended to backup DB before upgrading.
* Remove logic hook from **custom/modules/logic_hooks.php** by removing a line with the `asterlink javascript`.
Expand Down
34 changes: 17 additions & 17 deletions conf.example.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,23 +24,23 @@ dialplan:
# - {expr: "^\\d{7}$", repl: "+99878$0"}
# dial_format:
# - {expr: "^(\\+|)998(\\d{9})$", repl: "$2"}
bitrix24:
default_user: 1
webhook_url: https://mycrm.bitrix24.eu/rest/1/mytoken/
webhook_originate_token: my_originate_token
webhook_endpoint_addr: "0.0.0.0:5678"
# rec_upload: "http://mypbx.example.org/recfiles/"
# create_leads: true
# search_format:
# - {expr: ".*", repl: "$0"}
# - {expr: "^\\+(\\d{5})(\\d{7})$", repl: "+$1 $2"} # +XXXXX XXXXXXX
# - {expr: "^\\+(\\d{5})(\\d{3})(\\d{2})(\\d{2})$", repl: "+$1 $2 $3 $4"} # +XXXXX XXX XX XXX
# - {expr: "^\\+(\\d{5})(\\d{3})(\\d{2})(\\d{2})$", repl: "+$1 $2-$3-$4"} # +XXXXX XXX-XX-XXX
# - {expr: "^\\+(\\d{5})(\\d{3})(\\d{2})(\\d{2})$", repl: "$1 $2-$3-$4"} # XXXXX XXX XX XX
# - {expr: "^\\+(\\d{5})(\\d{3})(\\d{2})(\\d{2})$", repl: "$2 $3 $4"} # XXX XX XX
# - {expr: "^\\+(\\d{5})(\\d{3})(\\d{2})(\\d{2})$", repl: "$2-$3-$4"} # XXX-XX-XX
# - {expr: "^\\+(\\d{5})(\\d{3})(\\d{2})(\\d{2})$", repl: "(+$1) $2-$3-$4"} # (+XXXXX) XXX-XX-XX
# bitrix24:
# default_user: 1
# webhook_url: https://mycrm.bitrix24.eu/rest/1/mytoken/
# webhook_originate_token: my_originate_token
# webhook_endpoint_addr: "0.0.0.0:5678"
# # rec_upload: "http://mypbx.example.org/recfiles/"
# # create_leads: true
# # search_format:
# # - {expr: ".*", repl: "$0"}
# # - {expr: "^\\+(\\d{5})(\\d{7})$", repl: "+$1 $2"} # +XXXXX XXXXXXX
# # - {expr: "^\\+(\\d{5})(\\d{3})(\\d{2})(\\d{2})$", repl: "+$1 $2 $3 $4"} # +XXXXX XXX XX XXX
# # - {expr: "^\\+(\\d{5})(\\d{3})(\\d{2})(\\d{2})$", repl: "+$1 $2-$3-$4"} # +XXXXX XXX-XX-XXX
# # - {expr: "^\\+(\\d{5})(\\d{3})(\\d{2})(\\d{2})$", repl: "$1 $2-$3-$4"} # XXXXX XXX XX XX
# # - {expr: "^\\+(\\d{5})(\\d{3})(\\d{2})(\\d{2})$", repl: "$2 $3 $4"} # XXX XX XX
# # - {expr: "^\\+(\\d{5})(\\d{3})(\\d{2})(\\d{2})$", repl: "$2-$3-$4"} # XXX-XX-XX
# # - {expr: "^\\+(\\d{5})(\\d{3})(\\d{2})(\\d{2})$", repl: "(+$1) $2-$3-$4"} # (+XXXXX) XXX-XX-XX
# suitecrm:
# url: http://my.suitecrm/
# url: http://localhost/suitecrm/
# endpoint_token: my_endpoint_token
# endpoint_addr: "0.0.0.0:5678"
Loading

0 comments on commit 4dd6d5f

Please sign in to comment.