Synopsis

Gets, sets or clears the channel group.
Each channel can only be member of exactly one group per category; categories can be employed for more fine grained group management, and thus can help to assign more than one group name per channel.

Description

 GROUP([category])
 

Notes

A channel may belong to one group per category only. So, if one wants to make a channel belong both to Zap and SIP groups because two such channels are being bridged, one would have to use GROUP(in)=Zap and GROUP(out)=SIP (creating the categories in and out).

• This function may be both read from and written to.
• The category argument is optional; if empty you need to use GROUP() in your dialplan (note the empty brackets)
• *CLI> show function GROUP

Also note the existence of the special variable $OUTBOUND_GROUP: that group will be assigned to the channels created by the dial() app. There is also OUTBOUND_GROUP_ONCE which is unset after use. Both OUTBOUND_GROUP and OUTBOUND_GROUP_ONCE supports group@category (for exampe OUTBOUND_GROUP=mygroup@mycategory).

Return value

Returns the resulting string.

Examples

Example 1

 ; set the group name of the current channel to '3', and in addition assign the category 'cat8'
 exten => s,1,Set(GROUP(cat8)=3)
 exten => s,n,Set(GROUP(cat9)=hurray)
 exten => s,n,Set(foo1=${GROUP(cat8)})
 exten => s,n,Set(foo2=${GROUP(cat9)})

 ; the use of categories is optional
 exten => s,1,Set(GROUP()=MyGroup)
 exten => s,n,NoOp(This channel is member of group: ${GROUP()})
 
  ; clear the channels group for category 'cat8' (requires Asterisk 1.4.12 or later)
 exten => s,1,Set(GROUP(cat8)=)

Example 2

${VOIPMAX} is a user-set Global which limits the concurrent number of outbound VOIP calls

 [macro-stdvoip]
 ; ${ARG1} - full dial string
 ; Return ${DIALSTATUS} = CHANUNAVAIL if ${VOIPMAX} exceeded
 exten => s,1,Set(GROUP()=trunkgroup1)               ;Set Group
 exten => s,2,GotoIf($[${GROUP_COUNT(trunkgroup1)} > ${VOIPMAX}]?103) ;Exceeded?
 exten => s,3,Dial(${ARG1})               ;dial it
 exten => s,103,SetVar(DIALSTATUS=CHANUNAVAIL)               ;deny call

See also

• Asterisk cmd SetGroup with many examples
• Asterisk func group_count
• Asterisk func group_match_count
• Asterisk func group_list
• Asterisk variables
• Asterisk functions
• Asterisk groups
• Asterisk - documentation of application commands