Messages

list_messages

Client.list_messages(from_=None, to=None, from_date_time=None, to_date_time=None, direction=None, state=None, delivery_state=None, sort_order=None, size=None, **kwargs)

Get a list of user’s messages

Parameters:
  • from_ (str) – The phone number to filter the messages that came from
  • to (str) – The phone number to filter the messages that was sent to
  • from_date_time (str) – The starting date time to filter the messages (must be in yyyy-MM-dd hh:mm:ss format, like 2014-05-25 12:00:00.)
  • to_date_time (str) – The ending date time to filter the messages (must be in yyyy-MM-dd hh:mm:ss format, like 2014-05-25 12:00:00.)
  • direction (str) – Filter by direction of message, in - a message that came from the telephone network to one of your numbers (an “inbound” message) or out - a message that was sent from one of your numbers to the telephone network (an “outbound” message)
  • state (str) – The message state to filter. Values are ‘received’, ‘queued’, ‘sending’, ‘sent’, ‘error’
  • delivery_state (str) – The message delivery state to filter. Values are ‘waiting’, ‘delivered’, ‘not-delivered’
  • sort_order (str) – How to sort the messages. Values are ‘asc’ or ‘desc’
  • size (str) – Used for pagination to indicate the size of each page requested for querying a list of items. If no value is specified the default value is 25. (Maximum value 1000)
Return type:

types.GeneratorType
Returns:

list of messages

Example: Search for all messages and are in error:

message_list = api.list_messages()

for message in message_list:
    if message['state'] == 'error':
        print(message['id'])
## m-it6ewpyiyadfe
## m-pjnqofcjyadfe
## m-t2gspvs6iadfe
## m-shuh6d6pyadfe

send_message

Client.send_message(from_, to, text=None, media=None, receipt_requested=None, callback_url=None, callback_http_method=None, callback_timeout=None, fallback_url=None, tag=None, **kwargs)

Send a message (SMS or MMS)

Parameters:
  • from_ (str) – One of your telephone numbers the message should come from
  • to (str) – The phone number the message should be sent to
  • text (str) – The contents of the text message
  • media (list) – For MMS messages, a media url to the location of the media or list of medias to be sent send with the message.
  • receipt_requested (str) – Requested receipt option for outbound messages: ‘none’, ‘all’, ‘error’
  • callback_url (str) – The server URL where the events related to the outgoing message will be sent to
  • callback_http_method (str) – Determine if the callback event should be sent via HTTP GET or HTTP POST. Values are get or post Default is post
  • callback_timeout (str) – Determine how long should the platform wait for callbackUrl’s response before timing out (milliseconds).
  • fallback_url (str) – The server URL used to send the message events if the request to callbackUrl fails.
  • tag (str) – Any string, it will be included in the callback events of the message.
Return type:

str
Returns:

id of created message

Example: Send Text Message:

id = api.send_message(
    from_ = '+1234567980',
    to = '+1234567981',
    text = 'SMS message'
    )

Example: Send Picture Message:

id = api.send_message(
    from_ = '+1234567980',
    to = '+1234567981',
    media = ['http://host/path/to/file']
    )

send_messages

Client.send_messages(messages_data)

Send some messages by one request

Parameters:messages_data (list) – List of messages to send
Parameters of each message
from
One of your telephone numbers the message should come from
to
The phone number the message should be sent to
text
The contents of the text message
media
For MMS messages, a media url to the location of the media or list of medias to be sent send with the message.
receiptRequested
Requested receipt option for outbound messages: ‘none’, ‘all’, ‘error’
callbackUrl
The server URL where the events related to the outgoing message will be sent to
callbackHttpMethod
Determine if the callback event should be sent via HTTP GET or HTTP POST. Values are get or post Default is post
callbackTimeout
Determine how long should the platform wait for callbackUrl’s response before timing out (milliseconds).
fallbackUrl
The server URL used to send the message events if the request to callbackUrl fails.
tag
Any string, it will be included in the callback events of the message.
Return type:list
Returns:results of sent messages

Example: Bulk Send Picture or Text messages (or both):

results = api.send_messages([
    {'from': '+1234567980', 'to': '+1234567981', 'text': 'SMS message'},
    {'from': '+1234567980', 'to': '+1234567982', 'text': 'SMS message2'}
])

get_message

Client.get_message(id)

Get information about a message

Parameters:id (str) – id of a message
Return type:dict
Returns:message information

Example: Fetch information about single message:

my_message = api.get_message('m-abc123')
print(my_message)

## {
##     'callback_url'             :'https://yoursite.com/message',
##     'direction'               :'in',
##     'from'                    :'+19193047864',
##     'id'                      :'m-messageId',
##     'media'                   :[],
##     'message_id'               :'m-messageId',
##     'skip_mms_carrier_validation':True,
##     'state'                   :'received',
##     'text'                    :'Hey there',
##     'time'                    :'2017-02-01T21:10:32Z',
##     'to'                      :'+19191234567'
## }