Synopsis

 SetGroup(groupname[@category])

Description

Sets the channel group to the specified value. Equivalent to SetVar(GROUP=group).
Use categories to sort specifc groupnames into super-groups, which is equivalent to SetVar(GROUP_category=group). Each channel = call leg can have its own 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)

This command is deprecated in Asterisk v1.2. Instead use

 GROUP([category])=groupname
 Set(GROUP()=test)

Details

One of the major recent additions to Asterisk is app_groupcount, that you can use to limit the number of calls to, well, just about anything. A SIP peer, a PRI link, a call center staff member, a conference and calls to or from your boy and/or girlfriend

The command for setting a group is setgroup(), the command for enforcing a limitation in Asterisk 1.0.x is checkgroup().
For Asterisk 1.2.x CheckGroup() has been deprecated, instead use a combination of the GotoIf application and the GROUP_COUNT() function.

Please start using this instead of the incominglimit and outgoinglimit settings in sip.conf. Outgoinglimit is not working as expected and the more general solution with app_groupcount is a much better solution that works cross channels. This is an end-of-life warning for outgoinglimit - but note that incominglimit will stay!

Bug in Asterisk 1.0.x

According to bug 3067 transferred calls are not correctly managed by Asterisk 1.0.x with regard to the GROUP variable, so be aware!

Introduced with Asterisk 1.1 branch

See bug 2529

1. adds GetGroupMatchCount, which accepts a regex for group name and returns total count of all matching groups found
2. adds "group show channels" to the CLI, which lists all active channels that have groups assigned; also accepts a regex, which is matched against the group names

Example 1

exten => 999,1,SetGroup(moh)            ;Set Current Group to moh
exten => 999,2,CheckGroup(1)            ;Check moh does not have more than 1
exten => 999,3,Answer                   ;Answer the call
exten => 999,4,MusicOnHold(default)     ;Play default Music on hold
exten => 999,103,Busy                   ;Play busy if 1 person is already listening

Example 2 (not correct? Read below!)

Problem: How to limit incoming calls to SIP channels using the SetGroup & Checkgroup command. I don't want any call waiting on SIP channels!
Approach: One solution is to increment the GROUPCOUNT for both the caller and callee, to ensure the callee doesn't get a 2nd call while on the phone.


You will also want to ensure you SetGroup(${CALLERIDNUM}) before dialing any outgoing numbers as well (to PSTN,etc). ie:

Example 2 Revised.

After braking my head on the above code (it just didn't work) I'm revising it (I'm not the author of the first one).
The problem with the above code is that setgroup is only incremented once per channel, and each channel can only be associated to one group (it's just a variable that is part of a channel), so if I do a setgroup(foo), then when I do setgroup(bar) group foo is reset to 0 (provided foo was 0 before). The workaround is to use setvar(OUTBOUND_GROUP=foo), this will set the called channel into it's own group (foo).

Alternatives: Instead you might want to look into the Local channel construct with /n in order to create yet another call leg for the same call that then can have another GROUP variable assigned to it. Or use the new @categories.

So here we go:
Problem: How to limit incoming calls to SIP channels using the SetGroup & Checkgroup command. I don't want any call waiting on SIP channels!
Approach: One solution is to increment the GROUPCOUNT for both the caller and callee, to ensure the callee doesn't get a 2nd call while on the phone.


You will also want to ensure you SetGroup(${CALLERIDNUM}) before dialing any outgoing numbers as well (to PSTN,etc). ie:

There might also be a way to work around the above by using categories (example: setgroup(${CALLERIDNUM}@${CALLERIDNUM}), and setgroup(${EXTEN}@$EXTEN})) but I havn't tested it yet. Please update if you do. ==> See Example 6

Example 3

see the superdial macro page

• Superdial macro

Example 4 (Matt Riddell's Example)

The idea is that when you do setgroup you are putting this caller into a group. I.E. you could have

 exten => s,1,SetGroup(People_With_Short_Hair)

That would put anyone who visits this extension into the People_With_Short_Hair group.
Then if you do:

 exten => s,2,CheckGroup(678)

You can make sure that there are not more than 678 people already in the People_With_Short_Hair group.
If there are more than 678 people in the group then the application will go to the priority x+101 where x is the current priority.
See the ,2, on the checkgroup line? That's the current priority. So, 2+101=103.
So you could have a line

 exten => s,103,Playback(more_than_678_short_hair)

which would only be played if there are more than 678 people in the group.
If however there are less than or equal to the number inside the brackets for checkgroup (say for example there are 500 people who have short hair), then it will continue to the next priority.

As above, the current priority is 2 when you do the checkgroup, so the next priority is 3. This means that you can have the line:

 exten => s,3,Playback(less_than 678_short_hair)

Now, if we put them all together you'd end up with:

 exten => s,1,SetGroup(People_With_Short_Hair)
 exten => s,2,CheckGroup(678)
 exten => s,3,Playback(less_than_or_equal_to_678_short_hair)
 exten => s,103,Playback(more_than_678_short_hair)

---

Example 5 (Tagapache's Example) using the GROUP() function.

SetGroup and CheckGroup have been deprecated in (i think the rel I have is 1.0.7). I get
horribly confused with CVS Head and which release I have at any one point.

Instead you use the GROUP() function. Here is a working fragment from a SAIL-generated dial plan.
It works very well, choking the outbound calls at whatever number is set. This won't work on stable
releases, at least up to 1.0.9.

;********************************************************************
;
; S T D V O I P - with choke
;
;********************************************************************
[macro-stdvoip]
; 
; ${ARG1} - full dial string
; Return ${DIALSTATUS} = CHANUNAVAIL if ${VOIPMAX} exceeded
; 
;
exten => s,1,Set(GROUP()=OUTBOUND_GROUP)               ;Set Group
exten => s,2,GotoIf($[${GROUP_COUNT()} > ${VOIPMAX}]?103) ;Exceeded?
exten => s,3,Dial(${ARG1})               ;dial it
exten => s,103,SetVar(DIALSTATUS=CHANUNAVAIL)               ;deny call

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

Example 6 Using Categories in 1.0.x (Ramon's example)

Using categories you are able to set multiple groups on only one active channel.
So you are able to set the amount of calls on the called channel but also on the calling channel.

 exten => 200,1,SetGroup(CW@${EXTEN})
             ; Increase the number of calls on the called channel
 exten => 200,2,CheckGroup(1@CW)                     
             ; Check if called channel has more than 1 call
 exten => 200,3,SetGroup(CW@${CALLERIDNUM})
             ; Increase the number of calls on the calling channel
 exten => 200,4,Dial(SIP/200)
             ; Call the extension
 exten => 200,103,Busy
             ; Checkgroup jumped here if there was more than 1 call.

Note that this works in Asterisk 1.0.7 and no longer in new releases, See Example 5 for more info...
Also Note that a problem in Asterisk 1.0.x will cause incorrect data on transfer of calls

Example 7 Using Categories in 1.2.x (Ramon's example)

Using categories you are able to set multiple groups on only one active channel.
So you are able to set the amount of calls on the called channel but also on the calling channel.

exten => 200,1,Set(GROUP(${EXTEN})=OUTBOUND_GROUP)   
            ; Increase number of calls on the called channel
exten => 200,n,GotoIf($[${GROUP_COUNT(OUTBOUND_GROUP@${EXTEN})} > 1]?BLOCK)  
            ; Check if called channel has more than 1 call.
exten => 200,n,Set(GROUP(${CALLERIDNUM})=OUTBOUND_GROUP)
            ; Increase number of calls on the calling channel
exten => 200,n,Dial(SIP/200)
            ; Call the extension
exten => 200,n(BLOCK),Busy
            ; GotoIf jumped here if the was more than 1 call using labels

---

See also

• GROUP: Can also return the name of the group set on a channel when used in a read environment
• GROUP_LIST: Returns a space separated list of all of the groups set on a channel
• Asterisk cmd CheckGroup - only Asterisk 1.0.x, not in Asterisk 1.2.x
• Asterisk cmd GetGroupCount
• Asterisk cmd GetGroupMatchCount
• CLI command: "group show channels"
• Asterisk dialplan variable OUTBOUND_GROUP
• Superdial macro
• Asterisk groups

---

Go back to Asterisk - documentation of application commands