VGSM Manager Interface
From VoiSmart Open Source Wiki
Contents |
vgsm_sms_tx Action
The vGSM Asterisk's channel driver provides a manager action to send Short Messages (SMS). The action is named vgsm_sms_tx.
If the message does not contain characters in the GSM default alphabet the message will be sent with UCS2 but the available characters will be reduced to 80.
In pre-0.21.0 releases the action was named VGSMsmstx. This name is now deprecated and vgsm_sms_tx will be supported starting from 0.21.0.
Parameters
| Header | Usage | Description |
|---|---|---|
| To | Mandatory | The phone number to which to send the SMS. It may be in national format (347123456) or international format (+39347123456). The 00 or other operator-specific prefixes are not supported. |
| X-SMS-ME | Optional | Specifies the interface on which the SMS is sent. If not specified the SMS is sent on the first available interface. Huntgroups are supported using the huntgroup:name syntax, but sending will not currently be retried if there is a failure on the chosen module. Also, only sequential hunting is supported. |
| X-SMS-SMCC-Number | Optional | If present, forces the use of a specific Service Center. |
| X-SMS-Reject-Duplicates | Optional | Maps to TP-Reject-Duplicates (TP-RD), Ref. TS 100 901, §9.2.3.27 |
| X-SMS-Reply-Path | Optional | Maps to TP-Reply-Path (TP-RP), Ref. TS 100 901, §9.2.3.17 |
| X-SMS-Status-Report-Request | Optional | Maps to TP-Status-Report-Request (TP-SRR), Ref. TS 100 901, §9.2.3.5 |
| X-SMS-Message-Reference | Optional | Maps to TP-Message-Reference (TP-MR), Ref. TS 100 901, §9.2.3.6 |
| X-SMS-Validity-Period | Optional | Maps to TP-Validity-Period (TP-VP), Ref. TS 100 901, §9.2.3.12, specifies for how much time (in seconds, starting from now) the SMS message is valid and delivery should be attempted. If not specified the default value is 4 days. |
| X-SMS-Class | Optional | If specified sets the SMS class. Class 0 is used for flash SMSes, class 3 is used for normal messages. The use of other classes has to be evaluated. |
| X-SMS-Concatenate-RefID | Optional | In UDH Concatenate IE, specifies the Reference Id of the split message |
| X-SMS-Concatenate-Total-Messages | Optional | In UDH Concatenate IE, specifies the number of messages in which the main message is split |
| X-SMS-Concatenate-Sequence-Number | Optional | In UDH Concatenate IE, specifies the sequence number of this messages |
| Content-Type | Optional | Defines the content type; Only text/plain is currently supported |
| Content-Transfer-Encoding | Optional | Defines the content encoding, valid values are:
|
| Content
Content2 ContentN | Mandatory | The SMS body in the encoding specified in the Content-Transfer-Encoding or 7-bit ASCII if that header is missing. |
IMPORTANT: Asterisk Manager Interface does NOT support line lengths greater that 80 characters, including the header name, thus, it is mandatory to split the Content header in more headers with at most 65 characters each, unfortunately the splitting is supported starting from vstuff 1.0.0 which is not yet released. Please use a snapshot in the meantime. FIXME!! This statement needs to be confirmed. Asterisk version 1.4.14 allows a message of 160 char in one single Content: line. Will a message of size > 160 trigger more than 1 SMS?
Response statuses
Success
- 201 Message Sent
Temporary failures
- 400 Network out of order
- 401 Module is not ready
- 402 Module is not registered
- 403 Module is already sending a message
- 404 Cannot find an available module
- 405 Cannot allocate message
- 406 Out of memory
Permanent failures
- 501 Cannot find module
- 502 Services Center number not set
- 503 Cannot open iconv context
- 504 Invalid Content-Type
- 505 Unsupported content-Type
- 506 Unsupported Content-Transfer-Encoding
- 507 Charset conversion error
- 508 Cannot find huntgroup
- 509 Content: header missing
- 510 To: header missing
- 511 Message too big
- 512 Unspecified message preparation error
Example of a SMS sending session
Authentication
[root@voismart-4-000000 chan_vgsm]# telnet localhost 5038 Trying 127.0.0.1... Connected to localhost.localdomain (127.0.0.1). Escape character is '^]'. Asterisk Call Manager/1.0 Action: login Username: sms Secret: sms Response: Success Message: Authentication accepted
Simple ASCII message
Action: vgsm_sms_tx To: +393471234567 Content-type: text/plain; charset=ASCII Content: Ciao, questo e' un SMS. Niente caratteri 8-bit, qui. Status: 201 X-SMS-Reference: 22 Response: Success Message: Message sent
UTF-8 encoded message with characters in the GSM alphabet
Action: vgsm_sms_tx To: +393471234567 X-SMS-ME: vodafone X-SMS-Class: 3 X-SMS-SMCC-Number: +393492000200 Content-type: text/plain; charset=UTF-8 Content-Transfer-Encoding: base64 Content: VGVzdCBVVEYtOCBlbmNvZGluZyB3aXRoIGNoYXJhY3RlcnMgaW4gdGhlIEdTTSBhbHBoY Content2: WJldC4gQWNjZW50czogw6DDqMOsw7LDuSwgR3JlZWsgTGV0dGVyczogzqbOk86bzqnOo Content3: M6ozqPOmM6eLCBPdGhlcjogwqXCo8OHw5jDuMOFw6XigqzDhsOmw5/DicKkCg==
UTF-8 encoded message with characters outside the GSM alphabet
Action: vgsm_sms_tx To: +393471234567 X-SMS-ME: vodafone X-SMS-Class: 3 X-SMS-SMCC-Number: +393492000200 Content-type: text/plain; charset=UTF-8 Content-Transfer-Encoding: base64 Content: Q2hhcnMgb3V0c2lkZSBHU00gY2hhcnNldC4gQXJhYjog27Hbstuz27Tbtdu227fbuNu5L Content2: CBIZWI6INeQ15HXkteT15TXldeW15fXmNeZCg==
Concatenated messages
Action: vgsm_sms_tx To: +393471234567 X-SMS-ME: vodafone X-SMS-Concatenate-RefID: 58 X-SMS-Concatenate-Total-Messages: 2 X-SMS-Concatenate-Sequence-Number: 1 Content-type: text/plain; charset=ASCII Content: This is message part 1 of 2, that will be followed by part 2 of 2 which Content2: will be sent later. Action: vgsm_sms_tx To: +393471234567 X-SMS-ME: vodafone X-SMS-Concatenate-RefID: 58 X-SMS-Concatenate-Total-Messages: 2 X-SMS-Concatenate-Sequence-Number: 2 Content-type: text/plain; charset=ASCII Content: This is part 2 of 2, the message is now complete. We can thus send up Content2: to 255 parts for a total of 40,800 charaters (for just 38 Euros!)
Sending message using a huntgroup
Action: vgsm_sms_tx To: +34600123456 X-SMS-ME: huntgroup:safaricom Content-type: text/plain; charset=ASCII Content: This message is sent using one of the several ME in the group safaricom
vgsm_sms_rx Event
On reception of an inbound SMS (SMS-DELIVERY) the message will also be reported as a manager event, however, acknowledgment still relies on SMS spooler to handle the message. This event is generated starting from 0.21.0
Here follows an example of a received SMS via the manager interface:
Event: vgsm_sms_rx Privilege: call,all Received: from GSM module vodafone2, registered on 22210 (Vodafone, Italy); Wed, 20 Jun 2007 19:40:14 +0200 From: <+393471234567@sms.voismart.it> Subject: SMS message MIME-Version: 1.0 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: base64 Date: Wed, 20 Jun 2007 19:39:25 +0200 X-SMS-Message-Type: SMS-DELIVER X-SMS-Sender-NP: ISDN telephony X-SMS-Sender-TON: International X-SMS-Sender-Number: +393471234567 X-SMS-SMCC-NP: ISDN telephony X-SMS-SMCC-TON: International X-SMS-SMCC-Number: +393492000429 X-SMS-More-Messages-To-Send: yes X-SMS-Reply-Path: no X-SMS-User-Data-Header-Indicator: no X-SMS-Status-Report-Indication: no Content: SG8gY2hpYW1hdG8gYWxsZSAxOTozOSBkZWwgMjAvMDYvMDcuIEluZm9ybWF6aW9uZSBncmF0dWl0YSBkZWwgc2Vydml6aW8gQ0hJQU1BTUkgZGkgVm9kYWZvbmUu
vgsm_me_state Event
Whenever a ME (GSM module) changes working state, an event is generated. Here is an example of such type of events:
Event: vgsm_me_state Privilege: call,all X-vGSM-ME-State: POWERING_OFF X-vGSM-ME-Old-State: READY X-vGSM-ME-State-Change-Reason: Asterisk shutdown
The currently implemented states are:
CLOSED OFF POWERING_ON POWERING_OFF RESETTING WAITING_INITIALIZATION INITIALIZING READY WAITING_SIM WAITING_PIN FAILED
vgsm_net_state Event
Whenever the registration status of a GSM module changes, a vgsm_net_state event is generated. This event is available starting from 0.21.0. Here follows an example of such event:
Event: vgsm_net_state Privilege: call,all X-vGSM-GSM-Registration: REGISTERED_HOME
Valid registration states are:
- NOT_SEARCHING
- NOT_REGISTERED
- REGISTERED_HOME
- UNKNOWN
- REGISTRATION_DENIED
- REGISTERED_ROAMING
