Python client SDK for Sendbee Public API
Project description
Sendbee Python API Client
.' '. __
. . . (__\_
. . . -{{_(|8)
' . . ' ' . . ' (__/
Table of contents
Contacts
Contact Tags
Contact Fields
Conversations
- Fetch conversations
- Fetch conversation messages
- Fetch message templates
- Send template message
- Send message
Automation
Mics
Installation
> pip install sendbee-api
Initialization
from sendbee_api import SendbeeApi
api = SendbeeApi('__your_secret_key_here__', '__business_id_here__')
Contacts
Fetch contacts
contacts = api.contacts(
[tags=['...', ...]], [status='subscribed|unsubscribed'], [search_query='...']
)
for contact in contacts:
contact.id
contact.status
contact.folder
contact.created_at
contact.name
contact.phone
contact.email
contact.twitter_link
contact.facebook_link
for tag in contact.tags:
tag.id
tag.name
for note in contact.notes:
note.value
for contact_field in contact.contact_fields:
contact_field.key
contact_field.value
Subscribe contact
contact = api.subscribe_contact(
phone='+...',
# this is mandatory the most important information
# about the subscribing contact
[tags=['...', ...]],
# tag new contact
# if tag doesn't exist, it will be created
[name='...'], [email='...'],
[facebook_link='...'],[twitter_link='...'],
[address={
'line': '...',
'city': '...',
'postal_code': '...'
}],
[notes=[...]],
# write notes about your new subscriber
[contact_fields={'__field_name__': '__field_value__', ...}],
# fill contact fields with your data (value part)
# contact fields must be pre-created in Sendbee Dashboard
# any non-existent field will be ignored
[block_notifications=[True|False]],
# prevent sending browser push notification and email
# notification to agents, when new contact subscribes
# (default is True)
[block_automation=[True|False]]
# prevent sending automated template messages to newly
# subscribed contact (if any is set in Sendbee Dashboard)
# (default is True)
)
contact.id
contact.status
contact.folder
contact.created_at
contact.name
contact.phone
contact.email
contact.twitter_link
contact.facebook_link
for tag in contact.tags:
tag.id
tag.name
for note in contact.notes:
note.value
for contact_field in contact.contact_fields:
contact_field.key
contact_field.value
Update contact
contact = api.update_contact(
id='...',
# contact is identified with ID
[phone='+...'],
# this is the most important information
# about the subscribing contact
[tags=['...', ...]],
# tag new contact
# if tag doesn't exist, it will be created
[name='...'], [email='...'],
[facebook_link='...'],[twitter_link='...'],
[address={
'line': '...',
'city': '...',
'postal_code': '...'
}],
[notes=[...]],
# write notes about your new subscriber
# if there are notes already saved for this contact
# new notes will be appended
[contact_fields={'__field_name__': '__field_value__', ...}],
# fill contact fields with your data (value part)
# contact fields must be pre-created in Sendbee Dashboard
# any non-existent field will be ignored
# if there are fields already filled with data for this contact
# it will be overwritten with new data
)
contact.id
contact.status
contact.folder
contact.created_at
contact.name
contact.phone
contact.email
contact.twitter_link
contact.facebook_link
for tag in contact.tags:
tag.id
tag.name
for note in contact.notes:
note.value
for contact_field in contact.contact_fields:
contact_field.key
contact_field.value
Contact tags
Fetch contact tags
tags = api.tags([name='...'])
for tag in tags:
tag.id
tag.name
Create contact tag
tag = api.create_tag(name='...')
tag.id
tag.name
Update contact tag
tag = api.update_tag(id='...', name='...')
tag.id
tag.name
Update contact tag
response = api.delete_tag(id='...')
response.message
Contact fields
Fetch contact fields
contact_fields = api.contact_fields([search_query='...'])
for contact_field in contact_fields:
contact_field.slug
contact_field.name
contact_field.type
if contact_field.type == 'list':
contact_field.options
Create contact field
If a contact field type is a list, then you need to send a list options.
List options is a list of option names: ['option1', 'option2', ...]
contact_field = api.create_contact_field(
name='...', type='text|number|list|date|boolean',
[options=['...'. ...]] # if contact field type is list
)
contact_field.id
contact_field.slug
contact_field.name
contact_field.type
if contact_field.type == 'list':
contact_field.options
Update contact field
If a contact field type is a list, then you need to send a list options.
List options is a list of option names: ['option1', 'option2', ...]
contact_field = api.update_contact_field(
id='...', [name='...'], [type='text|number|list|date|boolean'],
[options=['...'. ...]] # if contact field type is list
)
contact_field.id
contact_field.slug
contact_field.name
contact_field.type
if contact_field.type == 'list':
contact_field.options
Delete contact field
response = api.delete_contact_field(id='...')
response.message
Conversations
Fetch conversations
conversations = api.conversations([folder='open|done|spam|notified'], [search_query='...'])
for conversation in conversations:
conversation.id
conversation.folder
conversation.chatbot_active
conversation.platform
conversation.created_at
conversation.contact.id
conversation.contact.name
conversation.contact.phone
conversation.last_message.direction
conversation.last_message.status
conversation.last_message.inbound_sent_at
conversation.last_message.outbound_sent_at
Fetch conversation messages
messages = api.messages(conversation_id='...')
for message in messages:
message.type
message.body
message.media_type
message.media_url
message.status
message.direction
message.sent_at
Fetch message templates
templates = api.message_templates(
[approved=True|False], [search_query='...']
)
for template in templates:
template.id
template.text
template.tags
template.keyword
template.language
template.approved
Send template message
response = api.send_template_message(
phone='+...',
template_keyword='...',
# every pre-created and approved message template
# is identified with a keyword
language='...',
# language keyword
# example: en (for english)
tags={'__tag_key__': '__tag_value__', ...}
# tags for template messages are parts of the message that need
# to be filled with your custom data
# example:
# template message: "Welcome {name}! How can we help you?"
# tags: {"name": contact.name}
)
response.status
response.conversation_id
# save this id, and when you get sent message status requests on
# your webhook, you'll get this same id to identify the conversation
Send message
You can send either text message or media message.
For media message, following formats are supported:
| Category | Formats |
|---|---|
| Audio | AAC, M4A, AMR, MP3, OGG OPUS |
| Video | MP4, 3GPP |
| Image | JPG/JPEG, PNG |
| Document | PDF, DOC, DOCX, PPT, PPTX, XLS, XLSX |
response = api.send_message(
phone='+...',
[text='...'],
# any kind of message text
[media_url='...']
# URL to a media.
# you need to upload it your self and send us the URL
)
response.status
response.conversation_id
# save this id, and when you get sent message status requests on
# your webhook, you'll get this same id to identify the conversation
Automation
Managing chatbot (automated responses) status settings
Every contact is linked to a conversation with an agent.
Conversation could be handled by an agent or a chatbot (automated responses).
Every time a message has been sent to a contact by an agent or using the API, the chatbot will automatically be turned off for that conversation.
Use the example below to change the chatbot status based on your use case.
api.chatbot_activity(conversation_id='...', active=True|False)
Misc
Exception handling
Every time something is not as it should be, like parameter is missing, parameter value is invalid, authentication fails, etc, API returns a http status code accordingly and an error message.
By using this client library, an error message is detected and taken, and an exception is raised, so you can handle it like this:
from sendbee_api import SendbeeRequestApiException
try:
api.send_template_message(...)
except SendbeeRequestApiException as e:
print(e)
Authenticate webhook request
After activating your webhook URL in Sendbee Dashboard, we will start sending requests on that URL depending on which webhook type is linked with that webhook URL.
Every request that we make will have authorization token in header, like this:
{
...
'X-Authorization': '__auth_token_here__',
...
}
To authenticate requests that we make to your webhook URL, take this token from request header and check it using Sendbee API Client:
from sendbee_api import SendbeeApi
api = SendbeeApi('__your_api_key_here__', '__your_secret_key_here__')
token = '...' # taken from the request header
if not api.auth.check_auth_token(token):
# error! authentication failed!
Warnings
Sometimes APi returns a worning so you could be warned about something.
The waning is displayed in standard output:
Debugging
This library has it's own internal debugging tool.
By default it is disabled, and to enable it, pass the debug parameter:
from sendbee_api import SendbeeApi
api = SendbeeApi(
'__your_api_key_here__', '__your_secret_key_here__',
'__business_id_here__', debug=True
)
Once you enabled the internal debug tool, every request to API will output various request and response data in standard output:
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
sendbee_api-0.11.0.tar.gz
(17.3 kB
view hashes)
Built Distribution
Close
Hashes for sendbee_api-0.11.0-py3-none-any.whl
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 82661909c3957317a2c03c357026c64d5efc2bea8c69c4ee5c127f4f92196522 |
|
| MD5 | 0cce90e63fc524fb9b055c4da1b47ac7 |
|
| BLAKE2b-256 | 29a500564271df073dce5909871078c5ea21e7f7a4429da4106e20bdd4bea3d4 |
