pchero / jade

Asterisk based call center solution

Jade

The jade is a free and open source unified communication system, which can fulfill a variety of roles for a range of industries and organizations who wish to contact to large numbers of people by phone or else in a short space of time.

The jade has been built using an Asterisk so that it can support almost everything about the Asterisk's features.

The jade can be used by anyone who has a need for mass outbound/inbound calling, voicemail system, agent call distributing, call recording and IVR service. Or may be used by other companies who wish to make calls on their own behalf, or by SaaS (Software as a Service) companies that want to provide bulk dialling and SMS broadcasting facilities to their own customers.

Features

• Restful API
• Event subscription via ZeroMQ and Websocket
• Strategical inbound/outbound call distributing
• Asterisk resource control
• Chatting
• Buddy managing
• WebRTC Call
• Dialplan
• Trunk
• SMS(WIP)
• Mail(WIP)
• Video call(WIP)
• Conference call(WIP)
• XMPP(WIP)

Manual

• https://jade-asterisk.readthedocs.io/en/latest/index.html

Docker

• All pre-setting Asterisk and jade project on a docker is ready.
  • $ docker pull pchero/jade-asterisk
  • https://github.com/pchero/jade-asterisk
  • https://hub.docker.com/r/pchero/jade-asterisk/

Demo

• jade

  • You can try apis to here.
  • http://project.pchero21.com:8081

• jade-me

  • https://github.com/pchero/jade-me
  • Simple user tool for jade.
  • You can try jade-me web application at here.
  • ID/Password
  • test1/test1, test2/test2, ...
  • https://project.pchero21.com:8202

Related project

• jade-me(https://github.com/pchero/jade-me)

  • 
  • Angular based simple web application for jade user.
  • Chat, Voice call, Buddy services.

• jade-manager(https://github.com/pchero/jade-manager)

  • 
  • Angular based simple web application for jade manager.
  • Provide simplized of resource handling.
  • Easy to add/modify/delete the resources such as user, trunk.

• jade-admin(https://github.com/pchero/jade-admin)

  • 
  • Angular based simple web application for jade adminstrator.
  • Provide micro level of resource handling.

• jade-agent(https://github.com/pchero/jade-agent)

  • Angular based simple web application for jade.
  • Agent tools for jade.

Library issue

• libevent

  • libevent-2.0.x has memory curruption problem. It's fixed in libevent-2.1.x.
    • It causes core crash the jade.
    • Need to use the libevnet-2.1.x or higher.
    • libevent/libevent#335

• libwebsocket

  • Required libevent option.
    • $ cd build
    • $ cmake -DLWS_WITH_LIBEVENT=1 ../
    • $ make && sudo make install
  • v2.4.1 has memory leak problem(warmcat/libwebsockets#1155)
    • Fixed in master branch.

• libevhtp

  • The libevhtp repository has been changed(https://github.com/criticalstack/libevhtp).
  • The libevhtp-v1.2.10, v1.2.11, v1.2.11n has memory leak problem(https://github.com/ellzey/libevhtp/issues/177).
  • It was fixed in develop branch. Recommand use the newst develop branch(https://github.com/ellzey/libevhtp.git).

License

• BSD License

Remember 2014.04.16

• Still remember 2014.04.16
• Rest in peace..
• https://en.wikipedia.org/wiki/Sinking_of_MV_Sewol

jade's Issues

Make separate http handler for ob http handle

The ob http handler consuming the space of the file too much.

It would be good idea make new file for them. :)

[ob] Remove old codes

rb_* functions are not in used anymore..

Let's clean up.

Support queue monitoring

Support those AMI events.

- QueueParams
- QueueMember
- QueueEntry

- QueueCallerAbandon
- QueueCallerJoin
- QueueCallerLeave
- QueueMemberAdded
- QueueMemberPause
- QueueMemberPenalty
- QueueMemberRemoved
- QueueMemberRinginuse
- QueueMemberStatus

Send Action at the beginning.

Action: QueueStatus

documentation. basic stuffs

documentation for below item first.

- /plans
- /plans/<uuid>

Support server status info

Implement API.

/status

Returns status of the server.

• Create status table.
• Keep update result Action: CoreStatus, Action: CoreSettings

Support AMI Event VarSet

Affect to the channel table.

Add the column variables.

"variables": {
  "key1": "val1",
  "key2": "val2",
  ...
}

Event: VarSet Example

Event: VarSet
Privilege: dialplan,all
Channel: SIP/agent-01-0000002b
ChannelState: 0
ChannelStateDesc: Down
CallerIDNum: agent-01
CallerIDName: <unknown>
ConnectedLineNum: <unknown>
ConnectedLineName: <unknown>
Language: en
AccountCode: 
Context: public
Exten: 4000
Priority: 1
Uniqueid: 1481278514.79
Linkedid: 1481278514.79
Variable: SIPURI
Value: sip:[email protected]:5060

Fix to ignore wrong dlma uuid

When the user send POST: /ob/dls with data, the jade backend doesn't verify the dlma uuid.

Need to fix it.

Support registry monitoring

Support registry monitoring.

Event: Registry
Privilege: system,all
ChannelType: SIP
Username: 3456
Domain: mysipprovider.com
Status: Request Sent

[ob] Make separate dlma handler

It's too much big file the ob_dl_handler.

Need to make it separate ob_dl_handler and ob_dlma_handler.

[ob] Change list result

Currently, all the list result of /ob/* apis return result as like the below.

{
  $defhdr,
  "reuslt": {
    "list": [
      "<uuid string>",
      ...
    ]
  }
}

But it should be changed like the below.

{
  $defhdr,
  "reuslt": {
    "list": [
      {"uuid": "<uuid string>"},
      ...
    ]
  }
}

[ob] Make test script for plan

Need to make test scripts.

- Create plan
- Update plan
- Delete plan

Support free seating monitoring

Support Rename ami event

Need to support rename ami event.

Event: Rename
Channel: <value>
Newname: <value>
Uniqueid: <value>

• Receive AMI event[Rename].
• Get channel info using the UniqueID.
• Update channel name.

Add installation manual

Add the installation manual

Need to handle OriginateResponse Failure

Currently, the jade_backend does not handle the Reponse fo the OriginateResponse Event.

But need to check the Response, because it cause wrong ob_dialing status update.

Event: OriginateResponse
Privilege: call,all
ActionID: 1113
Response: Failure
Channel: sip/agent-02sssdf
Application: park
Data: 
Reason: 0
Uniqueid: test 12 123 1236
CallerIDNum: <unknown>
CallerIDName: <unknown>

[ob] Support Preview dialing

Dials to the Agent first and, if the agent answer it, dials to the customer.

Deprecate /databases and /databases/

It's not an easy to keeping the ast-database info from the jade-backend.

Because there's no way to check the all database info and hard to recognize when the new database key and value set/deleted it.

It's better to deprecate the api.

make separate database asterisk and modules

Currently, the jade uses asterisk database and outbound database together.

But, if the jade uses the database in separate, it would be good to manage it.

Asterisk : Always recreate the database when the server is up.
Outboud : Clean up some of table when the server is up.

- Add outbound database file path.
- Add the database handler with context.

basic result format

Normal case

In normal case, the status code would be 200.

{
  "api_ver": "<version string>",
  "timestamp": "<UTC timestamp string>",
  "statuscode": <status code integer>,
  "result": {
    ....
  }
}

Error case

{
  "api_ver": "<version string>",
  "timestamp": "<UTC timestamp string>",
  "statuscode": <status code integer>,
  "error": {
    "code": <error code integer>,
    "message": "<detail error code message string>"
  }
}

Remove asterisk-outbound AMI message support

Support asterisk-outbound AMI is not good idea.

Because of, the asterisk-outbound module keeps the all the campaign/plan/.. info into module itself.
This makes duplicated outbound objects.

So, the jade can not handle the asterisk-outbound module.

Currently, there's code for support asterisk-outbound ami message. But need to be removed.

importing asterisk-outbound into jade

Import the res_outbound module to jade backend.

So, we could control the outbound dial list from the jade.

Fix wrong api description

Currently, there are lots of wrong description in the Resources api description.

For example, in the queue_params description, Data parameters description was wrong.

Call

GET /queue_params/

{
  "name": "<string>"
}
Data parameters

account: account info.

Need to fix it.

[ob] dl list error handler

Need to check invalid status of dls, and fix it.

- Get the all dialing/reserved status of dls.
- Validate dl info. (if there's no corresponding dl info in the dialing, update the status to idle.

[ob] Set to null all related item when it was deleted

Dlma

- Set to null related campaign's dlma info.

Plan

- Set to null related campaign's plan info.

Destination

- Set to null related campaign's destination info.

Should not affect to the dialing.
Once the dialing has created, the only status/result can be changed.

[ob] add the force option for all delete method

force=0

- Return false if there is referenced item to this.
- Delete given item.

force=1

- Set to null all the items which referenced to this(Make reference count to 0).
- Return false if there is referenced item to this.
- Delete given item.

[ob] Change plan dial_mode to predictive

AS-IS

#define DEF_PLAN_DIMAL_MODE     E_DIAL_MODE_NONE

TO-BE

#define DEF_PLAN_DIMAL_MODE     E_DIAL_MODE_PREDICTIVE

[ob] Handling variables

Currently, the jade_backend doesn't support variables.

Need to support it.

[ob] Make destination test script and automatic test script

Make simple destination test script and automatic test script.

Fix the libevent memory leak

There's memory leak report when the terminate the process.

The memory leak is not increasing and critical. But annoying. :(

[doc] Add device_state state table

Need to describe possible device_state's state.

"state": "UNAVAILABLE",

Support park info

parking lot

• Send request for getting all parking lots info at the beginning.

Action: Parkinglosts

• Keeps insert/replace the parking lot info

Event: Parkinglot

• Support APIs

/parking_lots
Returns all parking lot key info.

/parking_lots/ with key
Returns detail parking lot info of given key.

parked call

• Send request for getting all parked calls info at the beginning.

Action: ParkedCalls

• Keeps insert/replace/update/delete the parking lot info

Event: ParkedCall
Event: UnParkedCall
Event: ParkedCallGiveUp
Event: ParkedCallSwap

• Support APIs

/parked_calls
Returns all parked call key info.

/parked_calls/
Returns detail parked call info of given key.

Add the "/ob" prefix to the all outbound apis

Need to distinguish the outbound apis with normal api.

Because the outbound is some kind of plug-in/extra module.

Add the "/ob" prefix to the all outbound apis.

as-is

/campaigns
/campaigns/<uuid>

to-be

/ob/campaigns
/ob/campaigns/<uuid>

Caching the asterisk database

Caching the asterisk database.

Send request for initial asterisk database info

Keep update the asterisk database

Missing the Hangup result 0

There's no description about 0 value of hangup result.

Need to add it.

Result : Detail
0 :  Could not received hangup event yet.

[ob] Add the Action: Status for invalid dialing check

Need to add the invalid dialing record checker.

In somehow, the jade_backend could missing the channel hangup/dial end event.
If that, the jade_backend keeps the dialing info forever...

So the jade_backend needs to do something to prevent that.

It would be good, if the jade_backend send a below action request for every specified seconds.
And if the failed continued more than 3 times, then consider the dialing channel has missing.

List channel status.

Will return the status information of each channel along with the value for the specified channel variables.

Action: Status
ActionID: <value>
[Channel:] <value>
Variables: <value>
AllVariables: <value>

ActionID
Channel : The name of the channel to query for status.
Variables : Comma(,) separated list of variable to include.
AllVariables : If set to "true", the Status event will include all channel variables for the requested channel(s).
true
false

Reconnect handle

When the asterisk is starting, the jade_backend caused core dump.

Need to fix it to reconnect to the asterisk after second.

Add the port info for the registry account

Currently, the jade_backend used account as a primary key. And the account is combination of below information.

<username>@<hostname>

But if more than 2 accounts are use the same username and hostname, but different port number, it makes crash. Need to change to like the below.

<username>@<hostname>:<port>

Add library requirement

Requirement

- libbsd
- libjansson
- libevent
- libevhtp
- libsqlite3
- libssl

Support simple channel monitoring

Support below events.

- Newchannel
- Hangup

Increase log level for the API call

It's hard to know when the api call has been called.

Need to increase the log level for recognize the api has been called.

Add the /ob/dialings api

Need to support the dialings monitoring apis.

Support security request monitoring

Support security request monitoring

Event: AuthMethodNotAllowed
Event: ChallengeResponseFailed
Event: ChallengeSent
Event: InvalidAccountID
Event: InvalidPassword
Event: InvalidTransport
Event: LoadAverageLimit
Event: MemoryLimit
Event: RequestBadFormat
Event: RequestNotAllowed
Event: SuccessfulAuth

/securities

columns

Event:
EventTV : 
Severity : 
Service : 
EventVersion : 
AccountID : 
SessionID : 
LocalAddress : 
RemoteAddress : 
AttemptedTransfer : 
Module : 
SessionTV : 
Challenge : 
ReceivedChallenge : 
RecievedHash :
RequestType
RequestParams

Add SIGHUP handler

Add sighup handler.

As a tradition, when the jade-backend received SIGHUP signal, it will reload the configuration file.

Daemon programs sometimes use SIGHUP as a signal to restart themselves, the most common reason for this being to re-read a configuration file that has been changed.

Support device monitoring

Support devices info monitoring

Event: DeviceStateChange
Device: confbridge:1926527208
State: NOT_INUSE

...

- Send Action: DeviceStateList request at the beginning.
- Keep insert/update information using Event: DeviceStateChange event.

Replace db_handler to db_ctx_handler

Currently, main module uses the db_handler.

But db_handler is not designed for context switching...

Need to be changed to db_ctx_handler.

Add the pjsip AMI event handlers

Add the pjsip AMI event handlers.

Configuration file change

Currently, the jade-backend has strange categories in the configuration file.

And it could be possible to having different value of settings between configuration value and actually running process value. Because the jade-backend doesn't show the real(actually using) value to the configuration file.

So, need to do 2 things.

• Make it easy to categorize.
• Update the configuration file with real value after load the configuration file.

Categorize

AS-IS

{
  "serv_addr": "127.0.0.1",
  "serv_port": "5038",
  "username": "",
  "password": "",
  "loglevel": "7",
  
  "general" : {
    "result_filename" : "./outbound_result.json"
  },
  
  "database" : {
    "name": "./database.db"
  }
}

TO-BE

{
  "general": {
    "serv_addr": "127.0.0.1",
    "serv_port": "5038",
    "username": "",
    "password": "",
    "loglevel": "7",
    "database_name": "./database.db"
  },
  "ob": {
    "result_filename" : "./outbound_result.json"
  }
}

• general : Category for the asterisk basic options.
• ob: Category for the outbound module.

Update configuration file

• Create configuration options with default value in the memory.
• Load the configuration option from the configuration file.
• Update configuration options to the created configuration options using the loaded configuration options.

Documentation - Make separated outbound resource

Need to separate the outbound resource document.
Need to add the more detail description

• Plan

early_media
codecs
variables

• Dlma

• Dial List

[ob] Add the force option for the dlma delete

Currently, there's no rules when deleting the dlma.

But, it should be changed like below.

- It can't be delete if there's dl in the dlma without force option.
- If force option sets, delete all the dl info as well.
- If dlma has been deleted, should be deleted from the referenced campaign info also.

Add the force method parameter for the api call

DELETE /ob/dlmas/<uuid>?force=1

Add /peers api

Implement the /peers, /peers/ api.

/peers
- Returns list of peers name.

/peers/ with peer name
- Returns given peer's detail info.