View source for 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. <br/><br/>
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 parameter'''route_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|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|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|javascript global script]], external module, [[Regular expressions|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'''
* [[How to setup chat and short file transfer using MESSAGE Request Method|Using MESSAGE request method in older Yate versions]]
* [[Routing]]
* [[Xsip.generate]]

[[Category:Javascript]] [[Category:SIP]] [[Category:SMSC]] [[Category:SIP Methods]]