MessageBird API
handlers
10
Node
Javascript
Python beta
Ruby beta
Shell
curl
The handlers API requires you to accept the latest Terms of Service (ToS) in order to use it.

Please click here to accept.
We hope you enjoy documentation for the MessageBird handlers API on StdLib! This API can be used via the command line (shell), Node, Ruby, Python or as a generic HTTP call in any language. Check the code examples on the right associated with each API method for how to use this API in your language of choice.
API Description
Set StdLib functions as handlers for previously claimed MessageBird telephone numbers
# Setting SMS Message Response Handlers with MessageBird and StdLib With this service, you can set StdLib functions as handlers for MessageBird telephone numbers you've previously claimed. To see which numbers you've claimed, or to claim new phone numbers, you can use the [numbers.list](https://stdlib.com/@messagebird/lib/numbers) endpoint. After you set a handler for a MessageBird phone number with this service, it will trigger whenever that number receives a text message. If you're looking for how to send text messages from your claimed numbers, check out the [sms](https://stdlib.com/@messagebird/lib/sms) API. ### Setting Handlers To set a StdLib function that will run when one of your phone numbers receives an SMS message, use the `messagebird.handlers.sms.set` function. You can do this directly from the browser, but if you'd like to use the StdLib [command line tools](https://github.com/stdlib/lib), you could run something like: ``` $ lib messagebird.handlers.sms.set --number <your claimed number> --identifier <see below> ``` #### The Identifier Parameter The identifier parameter will correspond to a StdLib service you've previously published and will look something like this: ``` --identifier <your StdLib username>.<service name>[@<environment or version>].<function name> ``` If you want to call the latest released version of the service as a handler, `environment or version` is optional, and if you want to call the default endpoint for the service, `function name` is optional. #### StdLib Service Handler Input Parameters StdLib services set as handlers will receive four parameters when their assigned phone number receives a text message. ```javascript /** * @param {string} sender The phone number that sent the text to be handled * @param {string} receiver The StdLib phone number that received the SMS * @param {string} message The contents of the SMS * @param {string} createdDatetime Datetime when the SMS was sent * @returns {any} */ module.exports = async (sender, receiver, message, createdDatetime, context) => { // Do something here return 'Received SMS!'; }; ``` These parameters provide context allowing you to respond to incoming messages in a variety of ways, including sending responses to the sender or keeping a log of received texts. ### Clearing a Handler To clear a previously set handler, run `lib messagebird.handlers.sms.unset --number <your claimed number>`.
Sets a handler for incoming SMS messages for a phone number you own. Should be used after first initializing a phone number from the "numbers" API.
Authenticated   |   Pricing  ·  Free   |   Limit  ·  no rate limit
Unauthenticated   |   Forbidden  ·  Requires ToS
Parameters
number
required
string
The phone number you would like to set a handler for, you must own the number to set a handler. Check the numbers.list API to ensure you own the number.
current value set to
enter a test value
identifier
required
string
The service identifier for a StdLib function you would like to run in response to a received text message. For example, if your username is "user", your service is "service", the published environment is "dev", and the function is "method", your identifier is "user.service[@dev].method".
current value set to
enter a test value
Unsets (removes) a handler for incoming SMS messages for a phone number you own. This number should previously have been assigned a handler with the "handlers.sms.set" method.
Authenticated   |   Pricing  ·  Free   |   Limit  ·  no rate limit
Unauthenticated   |   Forbidden  ·  Requires ToS
Parameters
number
required
string
The phone number you previously assigned a handler to
current value set to
enter a test value
Made with by the MessageBird team with the help of StdLib.