Mac Home Automation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
=====Zadarma for sending SMS Messages=====

The [[https://zadarma.com/en/services/sms/|Zadarma VOIP]] Company offers a commercial solution to sending SMS messages with a well documented client API system that I’ve wrapped into a plugin at the request of XTension users, There are many ways to send SMS messages or get popup alerts on a phone, but depending on where you are in the world or what system you’re on this may be a good way to reliably get messages to your phone.

This is a commercial product and requires that you sign up and pay for the messages that you send, though the rates are very reasonable for the kind of volume any XTension user would be generating. They also require that you register the numbers that you wish to send to with their server so that it cannot be used to send spam messages to random phone numbers.

The plugin creates no Units only provides a scripting command to send the messages, see below or syntax and usage. Only a single instance of the plugin is necessary for a single Zadarma account. If you wish to use multiple accounts for some reason then additional instances of the plugin should be created with each accounts credentials.

====XTension Settings:====
{{:supported_hardware:zadarma_settings.png?600 |}}


The **API Key** and **API Secret** are created for you when you setup your account and configure the API. Those keys must be entered here in order for the API to recognize you and allow you to send your messages.

**Default Caller ID** This is the caller ID to use if no caller ID is specified in the command. You can specify a different caller ID for the individual calls to send a message if you wish. Note that those may also need to be registered with Zadarma before it will agree to put that as the sender of a message.

-----
====Sending SMS Messages:====
The usage is also described in the Interface Setup dialog above so it will always be handy in XTension.

The simplest usage is a call to the interface to tell it the telephone number to send the message to, and the message, In this case the default caller id you entered in the setup dialog will be used.

<code>
tell xInterface “Zadarma Alerts” to sendSMS( “the telephone number”, “your front door has opened while you were not home”)
</code>

replacing the name of the interface “Zararma Alerts” with whatever you named yours and inserting the proper telephone number.

Alternatively you can specify the caller ID number as a third parameter, making sure that this is a caller id that is registered with your API if that is required.

<code>
tell xInterface “Zadarma Alerts” to sendSMS( “the telephone number”, “your front door has opened”, “1234567890”)
</code>

-----
====Getting Your Balance:====

The 1.1 version of the plugin adds the ability to get your current balance on the account. This is not yet automated you have to tell it to ask the API for it. This does not automatically go into the value of a Unit but that can be trapped by the handler in the Interface script described below.

To get your balance use the scripting command:

<code>
tell xInterface “name of your Zadarma interface” to getBalance()
</code>

After this runs a log line will be written with the remaining balance similar to:
>Zadarma Balance Remaining: 24.8674 EUR

If you wish to use this number for sending yourself an alert or just setting the value of a pseudo to it in order to view in a web interface or a Unit list you can do so by creating a balanceUpdated( newBalance) handler in the Interface Script. 

To do this edit the Zadarma interface and click the Edit button in the Interface Script section at the bottom of the window. You’ll get a standard interface script template with the default events that call back into it. Use the Insert... toolbar button to get a popup list of other events you can add and you will see there the balanceUpdated callback listed. Select it and it will be added to the end of the script, or inserted wherever your cursor is in the script. The default handler is just another write log:

<code>
(*		 B A L A N C E   U P D A T E D

	This callback is run after the getBalance() command is run on the interface like:
		tell xInterface "name of this interface" to getBalance()
	
	the value is passed to the handler below. From here you could alert on a low balance,
	assign the value to a pseudo so that it can be seen easier in a web interface or XTension list
	or whatever else is of use to you.
	
	Note that this does not update automatically, you must call the getBalance() command. You might wish 
	to create an event to do that some number of minutes after sending any alert so that the value stays updated
	since the only way it's going to decrease is after you send an alert. Or if that is too many API calls you 
	may wish to just update the amount once a day via a scheduled event script.

*)

on balanceUpdated(newBalance)
	write log "The Zadarma balance is now2: " & newBalance
end balanceUpdated
</code>

Once you have that you can compare the value to some lower limit and alert yourself to buy some more messages, or set the value of a dimmable pseudo to it so that you can just watch the value. Note that the value is not updated automatically. You may wish to issue this command always a short time after sending any messages. Or just create a scheduled event to run once a day to keep it more or less updated. There are limits to the number of API hits they give you do you probably don’t want to run it every minute or something like that as it will only ever change if you are sending SMS messages.

-----
====Handling Errors:====

If the API call results in an error the runstate of the interface will change to Failed and the indicator on the interface will turn red. The specific error will be written to the log and also displayed in the interface status text to the right of the name in the interface list window.

You can trap this in a script the same as with any other interface error by implementing the interfaceError() handler in the same Interface script. You’ll find it already there with some documentation and it will pass you the message. So you can send some other kind of error or alert if Zadarma is refusing to send your messages.

<code>
on InterfaceError(TheMessage)
	write log “Zadarma has refused our call with a message of: " & TheMessage
end InterfaceError
</code>

Perhaps send an email instead with the [[dictionary:human:sendemail|Send Email Verb]]

-----
===History:====
  * The Zadarma plugin version 1.1 was first included in XTension version 9.4.2 in April of 2023. The 1.0 version was never officially released and was only ever given to the short list of folks using this for testing.