slack: update readme docs [skip ci]
[kamailio] / src / modules / slack / doc / slack_admin.xml
1 <?xml version="1.0" encoding='ISO-8859-1'?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4
5 <!-- Include general documentation entities -->
6 <!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
7 %docentities;
8
9 ]>
10 <!-- Module User's Guide -->
11
12 <chapter>
13
14         <title>&adminguide;</title>
15
16         <section>
17         <title>Overview</title>
18         <para>
19                 This module provides integration with Slack over webhooks.
20                 Slack integration (https://api.slack.com/messaging/webhooks)
21         </para>
22         <para>
23                 It relays on libcurl through http_client module.
24         </para>
25         </section>
26
27         <section>
28         <title>Dependencies</title>
29         <section>
30                 <title>&kamailio; Modules</title>
31                 <para>
32                         The following modules must be loaded before this module:
33                         <itemizedlist>
34                         <listitem><para>
35                         HTTP_CLIENT - the http_client module should be
36                         loaded first.
37                         </para></listitem>
38                         </itemizedlist>
39         </para>
40         </section>
41         <section>
42                 <title>External Libraries or Applications</title>
43                 <para>
44                 The following libraries or applications must be installed before running
45                 &kamailio; with this module loaded:
46                         <itemizedlist>
47                         <listitem>
48                         <para>
49                                 <emphasis>&libcurl;</emphasis>
50                         </para>
51                         </listitem>
52                         </itemizedlist>
53                 </para>
54         </section>
55         </section>
56
57         <section>
58         <title>Parameters</title>
59         <section id="slack.p.url">
60                 <title><varname>slack url</varname> (str)</title>
61                 <para>
62                         Slack webhook url
63                 </para>
64                 <para>
65                 <emphasis>
66                         Default value is not set (empty)
67                 </emphasis>
68                 </para>
69                 <example>
70                 <title>Set <varname>slack webhook URL</varname> parameter</title>
71                 <programlisting format="linespecific">
72 ...
73 modparam("slack", "slack_url", "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX")
74 ...
75                 </programlisting>
76                 </example>
77         </section>
78         <section id="slack.p.channel">
79                 <title><varname>channel</varname> (str)</title>
80                 <para>
81                         Slack channel name
82                 </para>
83                 <para>
84                 <emphasis>
85                         Default value is #kamailio
86                 </emphasis>
87                 </para>
88                 <example>
89                 <title>Set <varname>channel</varname> parameter</title>
90                 <programlisting format="linespecific">
91 ...
92 modparam("slack", "channel", "#kamailio")
93 ...
94 </programlisting>
95                 </example>
96         </section>
97         <section id="lwsc.p.username">
98                 <title><varname>username</varname> (str)</title>
99                 <para>
100                         Specify the username for the published message
101                 </para>
102                 <para>
103                 <emphasis>
104                         Default value is webhookbot.
105                 </emphasis>
106                 </para>
107                 <example>
108                 <title>Set <varname>username</varname> parameter</title>
109                 <programlisting format="linespecific">
110 ...
111 modparam("slack", "username", "webhookbot")
112 ...
113 </programlisting>
114                 </example>
115         </section>
116         <section id="slack.p.icon_emoji">
117                 <title><varname>icon_emoji</varname> (str)</title>
118                 <para>
119                         specify an emoji (using colon shortcodes, eg. :white_check_mark:)
120                         to use as the profile photo alongside the message.
121                 </para>
122                 <para>
123                 <emphasis>
124                         Default value is :ghost:
125                 </emphasis>
126                 </para>
127                 <example>
128                 <title>Set <varname>icon_emoji</varname> parameter</title>
129                 <programlisting format="linespecific">
130 ...
131 modparam("slack", "icon_emoji", ":ghost:")
132 ...
133 </programlisting>
134                 </example>
135         </section>
136
137         </section>
138
139         <section>
140         <title>Functions</title>
141         <section id="slack.f.slack_send">
142             <title>
143                 <function moreinfo="none">slack_send(format)</function>
144             </title>
145             <para>
146                 Send a formatted message to slack channel.
147                 </para>
148                 <para>
149                 The parameters are:
150                 </para>
151                 <itemizedlist>
152                         <listitem>
153                         <para>
154                         format - The formatted string to be send.
155                         </para>
156                         </listitem>
157                 </itemizedlist>
158                 <para>
159                 The parameters can contain pseudo-variables.
160                 </para>
161                 <para>
162                 This function can be used from ANY_ROUTE.
163                 </para>
164                 <example>
165                 <title><function>slack_send</function> usage</title>
166                 <programlisting format="linespecific">
167 ...
168     slack_send("Hello from Kamailio! caller=$fU;callee=$tU;callid=$ci");
169 ...
170 </programlisting>
171             </example>
172         </section>
173         </section>
174 </chapter>