Using SIP MESSAGE or how to enable chat messages in SIP

Starting with Yate 5 or svn revision 5629 Yate changed the way it handles SIP MESSAGE request method.

You can now enable chat messages between SIP clients or build custom applications based on SIP MESSAGE much easier.

Configuration

By default Yate doesn't accept SIP MESSAGE requests.

To allow them in set enable=yes in message section from ysipchan.conf.

[message]
; Controls the behaviour for SIP messaging

; enable: bool: Allow the SIP module to receive MESSAGE requests
enable=yes

; auth_required: bool: Automatically challenge all senders for authentication
;auth_required=enable

; async_process: bool: Process SIP MESSAGE asynchronously in their own thread
;async_process=enable

How it works

Default behaviour

When Yate receives SIP MESSAGE request from a client it will send a call.route message with parameterroute_type='msg'. This is the same behaviour as when Yate receives a SIP INVITE request for starting a phone call (except it won't add parameter route_type when receiving INVITE).

The call.route message will be handled by the routing module. You won't need to make other configurations if you already allowed SIP calls in Yate, besides enabling messages in ysipchan.conf as seen in the configuration above.

To test this if you don't already have a setup, set two clients in regfile.conf and send chat messages between the two of them. Regfile module will handle the authentication, registration and routing of the users. I used Twinkle clients to test this.

Custom applications

If you want to build a custom application with the use of SIP MESSAGE request then you will have to enable it from configuration and intercept the call.route message. You can do this in different ways: javascript global script, external module, regexroute etc.

We recommend you to use javascript global scripts for this.

Note: You can use javascript global scripts, but not javascript routing scripts because these scripts are not started on call.route with route_type=msg

SMSC

This is a basic example of storing received SIP MESSAGES in a database. Besides this you will need to add the logic that takes the messages from the database and sends them.

In javascript.conf in section scripts:

[scripts]
sip_messages=smsc.js

In mysqldb.conf define the database account:

[smsc]
database=smscdb
user=mysql
password=yate

Then in smsc.js from share/scripts directory in yate's sources (unless you configured a different path in javascript.conf or you installed yate) write the logic:

function onCallRoute(msg)
{
   Engine.output("Handling call.route caller="+msg.caller+" called="+msg.called);

   if (msg.route_type=="msg") {
       var m = new Message("database");
       m.account = "smsc";
       m.query = "INSERT INTO sms(caller,called,message) VALUES('" + sql_escape(msg.caller) + "','" + sql_escape(msg.called) + "','" + sql_escape(msg.xsip_body) + "')";
       m.dispatch();
   }
}

function sql_escape(val)
{
    // ..
    return val;
}

Message.install(onCallRoute, "call.route", 50);

Allowing SIP MESSAGE only for some users

Here is an example of a javascript global script that allows SIP MESSAGE only for user 101.

In javascript.conf in section scripts:

[scripts]
sip_messages=filter_sip_messages.js

Then in file filter_sip_messages.js from share/scripts:

function onCallRoute(msg)
{
   Engine.output("Handling call.route caller="+msg.caller+" called="+msg.called);

   if (msg.route_type=="msg") {
       if (msg.caller!="101") {
               Engine.output("Stopping SIP MESSAGE for user "+msg.caller);
               msg.reason = "rejected";
       }
   }
}

Message.install(onCallRoute, "call.route", 50);

Debugging

You don't have 'message' section in ysipchan.conf

If you don't have this section in ysipchan.conf then you need to update Yate to a newer version.

• After updating you will notice that ysipchan.conf.sample was changed.
• Backup old ysipchan.conf,
• Rename ysipchan.conf.sample to ysipchan.conf and
• Apply old configuration from backup file to new ysipchan.conf.
• You should have message section in ysipchan.conf
• Set enable=yes in message section
• Restart Yate

501 Not Implemented

If you receive '501 Not Implemented' from Yate it means that you didn't set 'enable=yes' in message section or Yate is too old and you need to install a newer version.

SIP/2.0 501 Not Implemented

405 Method Not Allowed

If you receive '405 Method Not Allowed' then the user you are trying to send a message to is offline.

SIP/2.0 405 Method Not Allowed

See also

• Using MESSAGE request method in older Yate versions
• Routing
• Xsip.generate