TEXTOPS module

Admin Guide

Overview

The module implements text based operations over the SIP message processed by OpenSIPS. SIP is a text based protocol and the module provides a large set of very useful functions to manipulate the message at text level, e.g., regular expression search and replace, Perl-like substitutions, checks for method type, header presence, insert of new header and date, etc.

Known Limitations

search ignores folded lines. For example, search(“(From|f):.*@foo.bar”) doesn’t match the following From header field:

From: medabeda
 <sip:medameda@foo.bar>;tag=1234

Dependencies

OpenSIPS Modules

The following modules must be loaded before this module:

No dependencies on other OpenSIPS modules.

External Libraries or Applications

The following libraries or applications must be installed before running OpenSIPS with this module loaded:

None.

Exported Functions

search(re)

Searches for the re in the message.

Meaning of the parameters is as follows:

re - Regular expression.

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

...
if ( search("[Ss][Ii][Pp]") ) { /*....*/ };
...

search_body(re)

Searches for the re in the body of the message.

Meaning of the parameters is as follows:

re - Regular expression.

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

...
if ( search_body("[Ss][Ii][Pp]") ) { /*....*/ };
...

search_append(re, txt)

Searches for the first match of re and appends txt after it.

Meaning of the parameters is as follows:

re - Regular expression.
txt - String to be appended.

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

...
search_append("[Oo]pen[Ss]er", " SIP Proxy");
...

search_append_body(re, txt)

Searches for the first match of re in the body of the message and appends txt after it.

Meaning of the parameters is as follows:

re - Regular expression.
txt - String to be appended.

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

...
search_append_body("[Oo]pen[Ss]er", " SIP Proxy");
...

replace(re, txt)

Replaces the first occurrence of re with txt.

Meaning of the parameters is as follows:

re - Regular expression.
txt - String.

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

...
replace("opensips", "Open SIP Server");
...

replace_body(re, txt)

Replaces the first occurrence of re in the body of the message with txt.

Meaning of the parameters is as follows:

re - Regular expression.
txt - String.

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

...
replace_body("opensips", "Open SIP Server");
...

replace_all(re, txt)

Replaces all occurrence of re with txt.

Meaning of the parameters is as follows:

re - Regular expression.
txt - String.

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

...
replace_all("opensips", "Open SIP Server");
...

replace_body_all(re, txt)

Replaces all occurrence of re in the body of the message with txt. Matching is done on a per-line basis.

Meaning of the parameters is as follows:

re - Regular expression.
txt - String.

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

...
replace_body_all("opensips", "Open SIP Server");
...

replace_body_atonce(re, txt)

Replaces all occurrence of re in the body of the message with txt. Matching is done over the whole body.

Meaning of the parameters is as follows:

re - Regular expression.
txt - String.

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

...
# strip the whole body from the message:
if(has_body() && replace_body_atonce("^.+$", ""))
        remove_hf("Content-Type");
...

subst(‘/re/repl/flags’)

Replaces re with repl (sed or perl like).

Meaning of the parameters is as follows:

‘/re/repl/flags’ - sed like regular expression. flags can be a combination of i (case insensitive), g (global) or s (match newline don’t treat it as end of line). ‘re’ - is regular expresion ‘repl’ - is replacement string - may contain pseudo-varibales ‘flags’ - substitution flags (i - ignore case, g - global)

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

...
# replace the uri in to: with the message uri (just an example)
if ( subst('/^To:(.*)sip:[^@]*@[a-zA-Z0-9.]+(.*)$/t:\1\u\2/ig') ) {};

# replace the uri in to: with the value of avp sip_address (just an example)
if ( subst('/^To:(.*)sip:[^@]*@[a-zA-Z0-9.]+(.*)$/t:\1$avp(sip_address)\2/ig') ) {};

...

subst_uri(‘/re/repl/flags’)

Runs the re substitution on the message uri (like subst but works only on the uri)

Meaning of the parameters is as follows:

‘/re/repl/flags’ - sed like regular expression. flags can be a combination of i (case insensitive), g (global) or s (match newline don’t treat it as end of line). ‘re’ - is regular expresion ‘repl’ - is replacement string - may contain pseudo-varibales ‘flags’ - substitution flags (i - ignore case, g - global)

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

...
# adds 3463 prefix to numeric uris, and save the original uri (\0 match)
# as a parameter: orig_uri (just an example)
if (subst_uri('/^sip:([0-9]+)@(.*)$/sip:3463\1@\2;orig_uri=\0/i')){$

# adds the avp 'uri_prefix' as prefix to numeric uris, and save the original
# uri (\0 match) as a parameter: orig_uri (just an example)
if (subst_uri('/^sip:([0-9]+)@(.*)$/sip:$avp(uri_prefix)\1@\2;orig_uri=\0/i')){$

...

subst_user(‘/re/repl/flags’)

Runs the re substitution on the message uri (like subst_uri but works only on the user portion of the uri)

Meaning of the parameters is as follows:

‘/re/repl/flags’ - sed like regular expression. flags can be a combination of i (case insensitive), g (global) or s (match newline don’t treat it as end of line). ‘re’ - is regular expresion ‘repl’ - is replacement string - may contain pseudo-varibales ‘flags’ - substitution flags (i - ignore case, g - global)

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

...
# adds 3463 prefix to uris ending with 3642 (just an example)
if (subst_user('/3642$/36423463/')){$

...
# adds avp 'user_prefix' as prefix to username in r-uri ending with 3642
if (subst_user('/(.*)3642$/$avp(user_prefix)\13642/')){$
...

subst_body(‘/re/repl/flags’)

Replaces re with repl (sed or perl like) in the body of the message.

Meaning of the parameters is as follows:

‘/re/repl/flags’ - sed like regular expression. flags can be a combination of i (case insensitive), g (global) or s (match newline don’t treat it as end of line). ‘re’ - is regular expresion ‘repl’ - is replacement string - may contain pseudo-varibales ‘flags’ - substitution flags (i - ignore case, g - global)

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

...
if ( subst_body('/^o=(.*) /o=$fU ') ) {};

...

filter_body(content_type)

Filters multipart body by leaving out all other body parts except the first body part of given type.

Meaning of the parameters is as follows:

content_type - Content type to be left in the body.

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

...
if (has_body("multipart/mixed")) {
    if (filter_body("application/sdp") {
        remove_hf("Content-Type");
        append_hf("Content-Type: application/sdp\r\n");
    } else {
        xlog("Body part application/sdp not found\n");
    }
}
...

append_to_reply(txt)

Append txt as header to all replies that will be generated by OpenSIPS for this request.

Meaning of the parameters is as follows:

txt - String which may contains pseudo-variables.

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE, ERROR_ROUTE.

...
append_to_reply("Foo: bar\r\n");
append_to_reply("Foo: $rm at $Ts\r\n");
...

append_hf(txt)

Appends ‘txt’ as header after the last header field.

Meaning of the parameters is as follows:

txt - Header field to be appended. The value can contain pseudo-variables which will be replaced at run time.

Note: Headers which are added in main route cannot be removed in further routes (e.g. failure routes). So, the idea is not to add there any headers that you might want to remove later. To add headers temporarely use the branch route because the changes you do there are per-branch.

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

...
append_hf("P-hint: VOICEMAIL\r\n");
append_hf("From-username: $fU\r\n");
...

append_hf(txt, hdr)

Appends ‘txt’ as header after first ‘hdr’ header field.

Meaning of the parameters is as follows:

txt - Header field to be appended. The value can contain pseudo-variables which will be replaced at run time.
hdr - Header name after which the ‘txt’ is appended.

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

...
append_hf("P-hint: VOICEMAIL\r\n", "Call-ID");
append_hf("From-username: $fU\r\n", "Call-ID");
...

insert_hf(txt)

Inserts ‘txt’ as header before the first header field.

Meaning of the parameters is as follows:

txt - Header field to be inserted. The value can contain pseudo-variables which will be replaced at run time.

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

...
insert_hf("P-hint: VOICEMAIL\r\n");
insert_hf("To-username: $tU\r\n");
...

insert_hf(txt, hdr)

Inserts ‘txt’ as header before first ‘hdr’ header field.

Meaning of the parameters is as follows:

txt - Header field to be inserted. The value can contain pseudo-variables which will be replaced at run time.
hdr - Header name before which the ‘txt’ is inserted.

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

...
insert_hf("P-hint: VOICEMAIL\r\n", "Call-ID");
insert_hf("To-username: $tU\r\n", "Call-ID");
...

append_urihf(prefix, suffix)

Append header field name with original Request-URI in middle.

Meaning of the parameters is as follows:

prefix - string (usually at least header field name).
suffix - string (usually at least line terminator).

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

...
append_urihf("CC-Diversion: ", "\r\n");
...

is_present_hf(hf_name)

Return true if a header field is present in message.

Meaning of the parameters is as follows:

hf_name - Header field name.(long or compact form)

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

...
if (is_present_hf("From")) log(1, "From HF Present");
...

append_time()

Adds a time header to the reply of the request. You must use it before functions that are likely to send a reply, e.g., save() from ‘registrar’ module. Header format is: “Date: %a, %d %b %Y %H:%M:%S GMT”, with the legend:

%a abbreviated week of day name (locale)
%d day of month as decimal number
%b abbreviated month name (locale)
%Y year with century
%H hour
%M minutes
%S seconds

Return true if a header was succesfully appended.

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

...
append_time();
...

is_method(name)

Check if the method of the message matches the name. If name is a known method (invite, cancel, ack, bye, options, info, update, register, message, subscribe, notify, refer, prack), the function performs method ID testing (integer comparison) instead of ignore case string comparison.

The ‘name’ can be a list of methods in the form of ‘method1|method2|…’. In this case, the function returns true if the SIP message’s method is one from the list. IMPORTANT NOTE: in the list must be only methods defined in OpenSIPS with ID (invite, cancel, ack, bye, options, info, update, register, message, subscribe, notify, refer, prack, publish; for more see: http://www.iana.org/assignments/sip-parameters).

If used for replies, the function tests the value of method field from CSeq header.

Meaning of the parameters is as follows:

name - SIP method name

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, and BRANCH_ROUTE.

...
if(is_method("INVITE"))
{
    # process INVITEs here
}
if(is_method("OPTION|UPDATE"))
{
    # process OPTIONs and UPDATEs here
}
...

remove_hf(hname)

Remove from message all headers with name “hname”

Returns true if at least one header is found and removed.

Meaning of the parameters is as follows:

hname - header name to be removed.

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE and BRANCH_ROUTE.

...
if(remove_hf("User-Agent"))
{
    # User Agent header removed
}
...

has_body(), has_body(mime)

The function returns true if the SIP message has a body attached. The checked includes also the “Content-Lenght” header presence and value.

If a paramter is given, the mime described will be also checked against the “Content-Type” header.

If the SIP message has a multipart body and mime is not a multipart type , it will search through all the parts for the given type.

It will not handle multi-layer multiparts

Meaning of the parameters is as follows:

mime - mime to be checked against the “Content-Type” header. If not present or 0, this check will be disabled.

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE and BRANCH_ROUTE.

...
if(has_body("application/sdp"))
{
    # do interesting stuff here
}
...

is_privacy(privacy_type)

The function returns true if the SIP message has a Privacy header field that includes the given privacy_type among its privacy values. See http://www.iana.org/assignments/sip-priv-values for possible privacy type values.

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE and BRANCH_ROUTE.

...
if(is_privacy("id"))
{
    # do interesting stuff here
}
...

strip_body(), strip_body(mime)

If the message has a body, this function deletes it, correcting Content-Length. This function also deletes the Content-Type header.

If a MIME type is specified it will delete the body if it has the same type or, if the message has a multipart body it will go through the parts and delete all those with the specified type.

It will not handle multi-layer multiparts

Meaning of the parameters is as follows:

mime - mime to be checked against the “Content-Type” header. If not present or 0, this check will be disabled.

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

...
strip_body();   #delete any body
strip_body("multipart/related") # delete a multipart/related body
strip_body("application/sdp") # delete all sdp bodies, even ones enclosed in multipart
...

add_body(body_text, new_content_type)

This function can be used to add a body to a message. If a body already exists, it will be replaced with the new one. The second parameter is the content type of the new body. It is optional: in case the function is used to replace an existing body with a body of the same type, there is no need to set this parameter. If the message has no body or if the types are different, it is compulsory to set this parameter.

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

...
add_body("Hello World!", "text/plain");
...

codec_exists (name [,clock] )

This function can be used to verify if a codec exists inside an sdp payload. It will search for the codec inside all streams from all sdp sessions. If it is found anywhere it will return TRUE otherwise it will return FALSE. The second parameter is optional, if it is not supplied any clockrate will match. Parameters are CASE INSENSITIVE.

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

...
codec_exists("speex");
or
codec_exists("GSM","8000");
...

codec_delete (name [,clock] )

This function can be used to delete a codec from inside an sdp payload. It will search for the codec inside all streams from all sdp sessions. If it is found anywhere it will be deleted from the mapping (“a=…”) and from the list of indexes (“m=…”). Returns TRUE if any deletion occured otherwise it will return FALSE. The second parameter is optional, if it is not supplied any clockrate will match and all will be deleted. Parameters are CASE INSENSITIVE.

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

...
codec_delete("speex");
or
codec_delete("GSM","8000");
...

codec_move_up (name [,clock] )

This function can be used to move a codec up in the list of indexes (“m=…”). It will search for the codec inside all streams from all sdp sessions. If it is found anywhere it will be moved to the top of the index list. Returns TRUE if any moves occured otherwise it will return FALSE. The second parameter is optional, if it is not supplied any clockrate will match and all codecs will be moved to the front while preserving their original ordering. Parameters are CASE INSENSITIVE.

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

...
codec_move_up("speex");
or
codec_move_up("GSM","8000");
...

codec_move_down (name [,clock] )

This function can be used to move a codec down in the list of indexes (“m=…”). It will search for the codec inside all streams from all sdp sessions. If it is found anywhere it will be moved to the back of the index list. Returns TRUE if any moves occured otherwise it will return FALSE. The second parameter is optional, if it is not supplied any clockrate will match and all codecs will be moved to the back while preserving their original ordering. Parameters are CASE INSENSITIVE.

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

...
codec_move_down("speex");
or
codec_move_down("GSM","8000");
...

...
/*
  This example will move speex with 8000 codec to the back of the list,
  then it will erase GSM with 8000 clock, and then it will bring all
  speex codecs to the front of the list. Speex/8000 will be behind any
  other speex.
*/
codec_move_down("speex","8000");
codec_delete("GSM","8000");
codec_move_up("speex");
...

codec_exists_re ( regexp )

This function has the same effect as codec_exists ( without the clock parameter ) the only difference is that it takes a POSIX regular expression as a parameter.

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

...
codec_exists_re("sp[a-z]*");
...

codec_delete_re ( regexp )

This function has the same effect as codec_delete ( without the clock parameter ) the only difference is that it takes a POSIX regular expression as a parameter.

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

...
codec_delete_re("PCMA|PCMU");
...

codec_delete_except_re ( regexp )

This function deletes all the codecs except those specified by the regular expression.

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

...
codec_delete_except_re("PCMA|PCMU");#will delete all codecs except PCMA and PCMU
...

codec_move_up_re ( regexp )

This function has the same effect as codec_move_up ( without the clock parameter ) the only difference is that it takes a POSIX regular expression as a parameter.

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

...
codec_move_up_re("sp[a-z]*");
...

codec_move_down_re ( regexp )

This function has the same effect as codec_move_down ( without the clock parameter ) the only difference is that it takes a POSIX regular expression as a parameter.

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.

...
codec_move_down_re("sp[a-z]*");
...

...
/*
  This example will move speex with 8000 codec to the back of the list,
  then it will erase GSM with 8000 clock, and then it will bring all
  speex codecs to the front of the list. Speex/8000 will be behind any
  other speex.
*/
codec_move_down("speex","8000");
codec_delete("GSM","8000");
codec_move_up("speex");
...

Known Limitations

Search functions are applied to the current message so modifications made to the sdp will be visible to the codec_exists functions( e.g. after calling codec_delete(“speex”) , codec_exists(“speex”) will return false ).

Contributors

By Commit Statistics

Top contributors by DevScore⁽¹⁾, authored commits⁽²⁾ and lines added/removed⁽³⁾

#	Name	DevScore	Commits	Lines++	Lines—
1.	Bogdan-Andrei Iancu (@bogdan-iancu)	42	35	319	221
2.	Daniel-Constantin Mierla (@miconda)	40	28	949	212
3.	Andrei Pelinescu-Onciul	28	21	459	147
4.	Andrei Dragus	20	7	1206	97
5.	Stefan Darius (@dariusstefan)	20	4	1313	200
6.	Jiri Kuthan (@jiriatipteldotorg)	18	14	301	53
7.	Jan Janak (@janakj)	12	6	496	27
8.	Juha Heinanen (@juha-h)	8	5	210	8
9.	Elena-Ramona Modroiu	6	3	205	14
10.	Henning Westerholt (@henningw)	6	3	36	77

All remaining contributors: Anca Vamanu, Marc Haisenko, Andreas Heise, Klaus Darilion, Andreas Granig, Maksym Sobolyev (@sobomax), Hugues Mitonneau, Razvan Crainea (@razvancrainea), Saúl Ibarra Corretgé (@saghul), Konstantin Bokarius, Edson Gellert Schubert, Ovidiu Sas (@ovidiusas).

(1) DevScore = author_commits + author_lines_added / (project_lines_added / project_commits) + author_lines_deleted / (project_lines_deleted / project_commits)

(2) including any documentation-related commits, excluding merge commits

(3) ignoring whitespace edits, renamed files and auto-generated files

By Commit Activity

#	Name	Commit Activity
1.	Stefan Darius (@dariusstefan)	Jun 2026 - Jul 2026
2.	Razvan Crainea (@razvancrainea)	Jun 2026 - Jun 2026
3.	Bogdan-Andrei Iancu (@bogdan-iancu)	Feb 2002 - Nov 2011
4.	Anca Vamanu	Oct 2008 - May 2011
5.	Ovidiu Sas (@ovidiusas)	Dec 2010 - Dec 2010
6.	Saúl Ibarra Corretgé (@saghul)	Apr 2010 - Apr 2010
7.	Andrei Dragus	Jul 2009 - Dec 2009
8.	Hugues Mitonneau	Feb 2009 - Feb 2009
9.	Andreas Granig	Jun 2008 - Jun 2008
10.	Daniel-Constantin Mierla (@miconda)	Jun 2005 - Mar 2008

All remaining contributors: Konstantin Bokarius, Edson Gellert Schubert, Henning Westerholt (@henningw), Juha Heinanen (@juha-h), Andreas Heise, Klaus Darilion, Marc Haisenko, Elena-Ramona Modroiu, Andrei Pelinescu-Onciul, Jan Janak (@janakj), Maksym Sobolyev (@sobomax), Jiri Kuthan (@jiriatipteldotorg).

(1) including any documentation-related commits, excluding merge commits

Documentation

Contributors

Last edited by: Razvan Crainea (@razvancrainea), Bogdan-Andrei Iancu (@bogdan-iancu), Andrei Dragus, Anca Vamanu, Andreas Granig, Daniel-Constantin Mierla (@miconda), Konstantin Bokarius, Edson Gellert Schubert, Juha Heinanen (@juha-h), Klaus Darilion, Marc Haisenko, Elena-Ramona Modroiu, Jan Janak (@janakj), Maksym Sobolyev (@sobomax), Jiri Kuthan (@jiriatipteldotorg), Andrei Pelinescu-Onciul.

License

All documentation files (i.e. .md extension) are licensed under the Creative Common License 4.0