noti-sdk-py 1.0.3

Lightweight Python SDK for WhatsApp messaging and bulk messaging via the Notibuzz Cloud REST API.

noti-sdk-py

noti-sdk-py is a lightweight Python SDK for interacting with the Notibuzz Cloud REST API. It enables Python applications to programmatically send WhatsApp messages, automate notifications, and run bulk messaging campaigns with minimal configuration. Ideal for backend services, automation scripts, and data-driven workflows.

📚 Official documentation & DEMO

• Full API documentation: https://notibuzz.com/api-docs — Complete REST reference for all endpoints, parameters, and examples.
• Request a DEMO: You can request a Notibuzz Cloud demonstration at notibuzz.com to try the platform before integrating.

Features

• ✅ Full Python support - Type hints and autocompletion
• ✅ Bulk messaging - Support for campaigns with anti-ban control
• ✅ Async queue - Background message sending
• ✅ All endpoints - Sessions, Profile, Chatting, Status, Chats, Contacts
• ✅ Campaign control - Stop, resume and check availability
• ✅ Pythonic API - Clean and intuitive interface

Installation

pip install noti-sdk-py

Quick Setup

Option 1: Environment Variables

export NOTI_URL="your_base_url"
export NOTI_KEY="your_api_key_here"

Option 2: Code Configuration

Recommended syntax (dict):

from noti_sdk_py import configure_client

configure_client({
    'noti_url': 'your_base_url',
    'noti_api_key': 'your_api_key'
})

Traditional syntax (also supported):

configure_client('your_base_url', 'your_api_key')

Basic Usage

Send a text message

from noti_sdk_py import configure_client, send_message
import os

configure_client({
    'noti_url': os.getenv('NOTI_URL'),
    'noti_api_key': os.getenv('NOTI_KEY')
})

result = send_message(
    body={
        'type': 'text',
        'payload': {
            'session': 'default',
            'chatId': '[e-mail]',
                    'text': 'Hello from the SDK!'
        }
    }
)

print('Message sent:', result)

List sessions

from noti_sdk_py import list_sessions

sessions = list_sessions(
    query={'all': True}  # Include STOPPED sessions
)

print('Available sessions:', sessions)

Bulk Messaging

The SDK supports bulk messaging with interval and anti-ban control:

from noti_sdk_py import send_message

# Bulk sending with multiple messages
result = send_message(
    body={
        'intervalMs': 20000,  # 20 seconds between messages
        'messages': [
            {
                'type': 'text',
                'payload': {
                    'session': 'default',
                    'chatId': '[e-mail]',
                    'text': 'Message 1'
                }
            },
            {
                'type': 'text',
                'payload': {
                    'session': 'default',
                    'chatId': '[e-mail]',
                    'text': 'Message 2'
                }
            },
            {
                'type': 'image',
                'payload': {
                    'session': 'default',
                    'chatId': '[e-mail]',
                    'file': {
                        'mimetype': 'image/jpeg',
                        'filename': 'foto.jpg',
                        'url': 'https://example.com/image.jpg'
                    },
                    'caption': 'Check out this image'
                }
            }
        ],
        'meta': {
            'campaignId': 'campaign-123',
            'requester': 'my-app',
            'origin': 'web'
        }
    }
)

print('Campaign enqueued:', result)
# {'enqueued': True, 'jobId': 'send-bulk-...', 'count': 3, 'intervalMs': 20000}

Individual message using send_message

from noti_sdk_py import send_message

# You can also send an individual message
result = send_message(
    body={
        'type': 'text',
        'payload': {
            'session': 'default',
            'chatId': '[e-mail]',
                    'text': 'Single message'
        }
    }
)

Async Sending

You can send messages asynchronously (queued) using the async_ parameter:

from noti_sdk_py import send_message

# The message will be queued and processed in the background
send_message(
    body={
        'type': 'text',
        'payload': {
            'session': 'default',
            'chatId': '[e-mail]',
            'text': 'Async message'
        }
    },
    async_=True  # Queue the message
)

# Also works with other message types
send_message(
    body={
        'type': 'image',
        'payload': {
            'session': 'default',
            'chatId': '[e-mail]',
            'file': {
                'mimetype': 'image/jpeg',
                'url': 'https://example.com/image.jpg'
            }
        }
    },
    async_=True
)

Bulk Campaign Control

Check availability

from noti_sdk_py import bulk_availability

availability = bulk_availability(
    query={'requester': 'my-app'}
)

print('Availability:', availability)
# {'available': True, 'current': 1, 'max': 2, 'origin': 'noti-sender-bridge'}

Stop a campaign

from noti_sdk_py import bulk_stop_campaign

bulk_stop_campaign(
    path_params={'id': 'campaign-123'},
    body={
        'sessions': ['default']  # Optional: stop only in these sessions
    }
)

Resume a campaign

from noti_sdk_py import bulk_resume_campaign

bulk_resume_campaign(
    path_params={'id': 'campaign-123'},
    body={
        'sessions': ['default']  # Optional: resume only in these sessions
    }
)

Bulk Jobs (list, pause, resume, cancel)

When you send bulk messages via the API, each campaign is enqueued as a job. You can list jobs, pause a running job, resume it, or cancel it.

from noti_sdk_py import (
    list_bulk_jobs,
    pause_bulk_job,
    resume_bulk_job,
    cancel_bulk_job,
)

# List all bulk jobs (waiting, delayed, active)
result = list_bulk_jobs()
# result: {"ok": True, "jobs": [...], "total": N}

# Pause a job (e.g. to stop sending temporarily)
pause_bulk_job(path_params={"jobId": "send-bulk-1234567890-ab12"})

# Resume a paused job
resume_bulk_job(path_params={"jobId": "send-bulk-1234567890-ab12"})

# Cancel a job (removes from queue, releases locks)
cancel_bulk_job(path_params={"jobId": "send-bulk-1234567890-ab12"})

Examples by Category

Sessions

from noti_sdk_py import list_sessions, get_session, get_session_me

# List all sessions
sessions = list_sessions(query={'all': True})

# Get session information
session = get_session(path_params={'session': 'default'})

# Get authenticated account information
me = get_session_me(path_params={'session': 'default'})

Profile

from noti_sdk_py import (
    get_my_profile,
    set_profile_name,
    set_profile_status,
    set_profile_picture,
    delete_profile_picture
)

# Get profile
profile = get_my_profile(path_params={'session': 'default'})

# Update profile name
set_profile_name(
    path_params={'session': 'default'},
    body={'name': 'My New Name'}
)

# Update status (About)
set_profile_status(
    path_params={'session': 'default'},
    body={'status': '🎉 Using Noti Sender!'}
)

# Update profile picture
set_profile_picture(
    path_params={'session': 'default'},
    body={
        'file': {
            'mimetype': 'image/jpeg',
            'filename': 'avatar.jpg',
            'url': 'https://example.com/avatar.jpg'
        }
    }
)

# Delete profile picture
delete_profile_picture(path_params={'session': 'default'})

Chatting

Important: All messages are sent through the generic send_message endpoint. Supported types: text, image, file, voice, video, link-custom-preview, seen, poll, location, contact-vcard, forward, list.

Direct endpoints (don't go through send_message): reaction, start_typing, stop_typing.

from noti_sdk_py import send_message, reaction, start_typing, stop_typing

# Send text
send_message(
    body={
        'type': 'text',
        'payload': {
            'session': 'default',
            'chatId': '[e-mail]',
            'text': 'Hello!'
        }
    }
)

# Send image
send_message(
    body={
        'type': 'image',
        'payload': {
            'session': 'default',
            'chatId': '[e-mail]',
            'file': {
                'mimetype': 'image/jpeg',
                'filename': 'foto.jpg',
                'url': 'https://example.com/image.jpg'
            },
            'caption': 'Check this out'
        }
    }
)

# Send file
send_message(
    body={
        'type': 'file',
        'payload': {
            'session': 'default',
            'chatId': '[e-mail]',
            'file': {
                'mimetype': 'application/pdf',
                'filename': 'document.pdf',
                'url': 'https://example.com/document.pdf'
            },
            'caption': 'Important document'
        }
    }
)

# Send voice note
send_message(
    body={
        'type': 'voice',
        'payload': {
            'session': 'default',
            'chatId': '[e-mail]',
            'file': {
                'mimetype': 'audio/ogg; codecs=opus',
                'url': 'https://example.com/voice.opus'
            },
            'convert': False  # True if you need format conversion
        }
    }
)

# Send video
send_message(
    body={
        'type': 'video',
        'payload': {
            'session': 'default',
            'chatId': '[e-mail]',
            'file': {
                'mimetype': 'video/mp4',
                'filename': 'video.mp4',
                'url': 'https://example.com/video.mp4'
            },
            'caption': 'Watch this video',
            'asNote': False,  # True for round video
            'convert': False
        }
    }
)

# Send poll
send_message(
    body={
        'type': 'poll',
        'payload': {
            'session': 'default',
            'chatId': '[e-mail]',
            'poll': {
                'name': 'What is your favorite color?',
                'options': ['Red', 'Blue', 'Green'],
                'selectableOptionsCount': 1
            }
        }
    }
)

# Send location
send_message(
    body={
        'type': 'location',
        'payload': {
            'session': 'default',
            'chatId': '[e-mail]',
            'latitude': -12.097633,
            'longitude': -77.019575,
            'title': 'Our office'
        }
    }
)

# Send contact (vCard)
send_message(
    body={
        'type': 'contact-vcard',
        'payload': {
            'session': 'default',
            'chatId': '[e-mail]',
            'contacts': [
                {
                    'fullName': 'John Doe',
                    'organization': 'Company Name',
                    'phoneNumber': '[phone]',
                    'whatsappId': '51987654321'
                }
            ]
        }
    }
)

# Send list (interactive list)
send_message(
    body={
        'type': 'list',
        'payload': {
            'session': 'default',
            'chatId': '[e-mail]',
            'message': {
                'title': 'Simple Menu',
                'description': 'Please choose an option',
                'footer': 'Thank you!',
                'button': 'Choose',
                'sections': [
                    {
                        'title': 'Main',
                        'rows': [
                            {
                                'title': 'Option 1',
                                'rowId': 'option1',
                                'description': 'Option 1 description'
                            },
                            {
                                'title': 'Option 2',
                                'rowId': 'option2',
                                'description': 'Option 2 description'
                            }
                        ]
                    }
                ]
            }
        }
    }
)

# Send message with custom link preview
send_message(
    body={
        'type': 'link-custom-preview',
        'payload': {
            'session': 'default',
            'chatId': '[e-mail]',
            'text': 'Check this out! https://github.com/',
            'linkPreviewHighQuality': True,
            'preview': {
                'image': {
                    'url': 'https://picsum.photos/400/300'
                },
                'url': 'https://github.com/',
                'title': 'Your Title',
                'description': 'Check this out, amazing!'
            }
        }
    }
)

# Forward message
send_message(
    body={
        'type': 'forward',
        'payload': {
            'session': 'default',
            'chatId': '[e-mail]',
            'forward': {
                'keyId': '[e-mail]_AAAAAAAAAAAAAAAAAAAA'
            }
        }
    }
)

# Mark as seen using sendMessage with type 'seen'
send_message(
    body={
        'type': 'seen',
        'payload': {
            'session': 'default',
            'chatId': '[e-mail]',
            'messages': ['[e-mail]_AAAAAAAAAAAAAAAAAAAA']
        }
    }
)

# React to a message (direct endpoint)
reaction(
    body={
        'session': 'default',
        'messageId': '[e-mail]_3EB0EB3DF63D6AF1112A85',
        'reaction': '👍'
    }
)

# Start typing (direct endpoint)
start_typing(
    body={
        'session': 'default',
        'chatId': '[e-mail]'
    }
)

# Stop typing (direct endpoint)
stop_typing(
    body={
        'session': 'default',
        'chatId': '[e-mail]'
    }
)

Status (Stories)

from noti_sdk_py import status_text, status_image, status_voice, status_video, status_delete

# Create text Story
status_text(
    path_params={'session': 'default'},
    body={
        'contacts': [],  # [] to send to all
        'text': 'Check this out! https://github.com/',
        'backgroundColor': '#38b42f',
        'font': 0,
        'linkPreview': True
    }
)

# Create image Story
status_image(
    path_params={'session': 'default'},
    body={
        'contacts': ['[e-mail]'],
        'caption': 'My Story',
        'file': {
            'mimetype': 'image/jpeg',
            'filename': 'status.jpg',
            'url': 'https://example.com/image.jpg'
        }
    }
)

# Create voice Story
status_voice(
    path_params={'session': 'default'},
    body={
        'contacts': ['[e-mail]'],
        'backgroundColor': '#38b42f',
        'file': {
            'mimetype': 'audio/ogg; codecs=opus',
            'url': 'https://example.com/voice.opus'
        },
        'convert': False
    }
)

# Create video Story
status_video(
    path_params={'session': 'default'},
    body={
        'contacts': ['[e-mail]'],
        'caption': 'My video Story',
        'file': {
            'mimetype': 'video/mp4',
            'filename': 'status.mp4',
            'url': 'https://example.com/status.mp4'
        },
        'convert': False
    }
)

# Delete Story
status_delete(
    path_params={'session': 'default'},
    body={
        'id': '3EB0B4B74FB349EEC971A6'
    }
)

Chats

from noti_sdk_py import (
    chats_get,
    chats_overview_get,
    chats_overview_post,
    chats_get_messages,
    chats_get_message,
    chats_read_messages,
    chats_delete_message,
    chats_edit_message,
    chats_pin_message,
    chats_unpin_message,
)

# List chats
chats = chats_get(path_params={'session': 'default'})

# Get chat overview
overview = chats_overview_get(
    path_params={'session': 'default'},
    query={'limit': 20, 'offset': 0}
)

# Get chat overview (POST method with filters)
overview_post = chats_overview_post(
    path_params={'session': 'default'},
    body={
        'limit': 20,
        'offset': 0,
        'ids': ['[e-mail]']  # Optional: filter by chat IDs
    }
)

# Get chat messages
messages = chats_get_messages(
    path_params={
        'session': 'default',
        'chatId': '[e-mail]'
    },
    query={
        'limit': 50,
        'offset': 0,
        'downloadMedia': True
    }
)

# Get a specific message by ID
message = chats_get_message(
    path_params={
        'session': 'default',
        'chatId': '[e-mail]',
        'messageId': '[e-mail]_AAAAAAAAAAAAAAAAAAAA'
    },
    query={'downloadMedia': True}
)

# Mark messages as read
chats_read_messages(
    path_params={
        'session': 'default',
        'chatId': '[e-mail]'
    },
    query={
        'messages': 30,  # Number of messages
        'days': 7  # Days back
    }
)

# Edit message
chats_edit_message(
    path_params={
        'session': 'default',
        'chatId': '[e-mail]',
        'messageId': '[e-mail]_AAAAAAAAAAAAAAAAAAAA'
    },
    body={
        'text': 'Edited message',
        'linkPreview': True
    }
)

# Delete message
chats_delete_message(
    path_params={
        'session': 'default',
        'chatId': '[e-mail]',
        'messageId': '[e-mail]_AAAAAAAAAAAAAAAAAAAA'
    }
)

# Pin message
chats_pin_message(
    path_params={
        'session': 'default',
        'chatId': '[e-mail]',
        'messageId': '[e-mail]_AAAAAAAAAAAAAAAAAAAA'
    },
    body={
        'duration': 86400  # 24 hours
    }
)

# Unpin message
chats_unpin_message(
    path_params={
        'session': 'default',
        'chatId': '[e-mail]',
        'messageId': '[e-mail]_AAAAAAAAAAAAAAAAAAAA'
    }
)

Contacts

from noti_sdk_py import (
    contacts_get_all,
    contacts_get_basic,
    contacts_check_exists,
    contacts_profile_picture,
    contacts_get_about,
    contacts_block,
    contacts_unblock,
    contacts_upsert,
)

# List all contacts
all_contacts = contacts_get_all(query={'session': 'default'})

# Get basic information
contact = contacts_get_basic(
    query={
        'session': 'default',
        'contactId': '[e-mail]'
    }
)

# Check if a number exists in WhatsApp
exists = contacts_check_exists(
    query={
        'session': 'default',
        'phone': '51987654321'
    }
)

# Get profile picture
picture = contacts_profile_picture(
    query={
        'session': 'default',
        'contactId': '[e-mail]',
        'refresh': False
    }
)

# Get contact about (status)
about = contacts_get_about(
    query={
        'session': 'default',
        'contactId': '[e-mail]'
    }
)

# Block contact
contacts_block(
    path_params={
        'session': 'default',
        'chatId': '[e-mail]'
    }
)

# Unblock contact
contacts_unblock(
    path_params={
        'session': 'default',
        'chatId': '[e-mail]'
    }
)

# Create or update contact
contacts_upsert(
    path_params={
        'session': 'default',
        'chatId': '[e-mail]'
    },
    body={
        'firstName': 'John',
        'lastName': 'Doe'
    }
)

Error Handling

from noti_sdk_py import send_message
import requests

try:
    result = send_message(
        body={
            'type': 'text',
            'payload': {
                'session': 'default',
                'chatId': '[e-mail]',
                'text': 'Hello'
            }
        }
    )
    print('Success:', result)
except requests.RequestException as error:
    print('Error:', str(error))
    # Error message includes HTTP code and details
    # Example: "HTTP 401 Unauthorized - { 'error': 'invalid X-Api-Key' }"

Requirements

• Python >= 3.8
• requests >= 2.28.0

More Examples

For complete, runnable examples organized by category, see the examples/ directory:

• Sessions: List, get session info, get authenticated account
• Profile: Get profile, update name/status/picture, delete picture
• Chatting: All message types (text, image, file, voice, video, poll, location, contact, list, link preview, forward), reactions, typing indicators
• Status: Text, image, voice, video statuses, delete status
• Chats: List chats, get messages, edit/delete/pin/unpin messages, mark as read
• Contacts: Get contacts, check existence, profile pictures, block/unblock, upsert

Run any example:

python examples/sessions/list_sessions.py
python examples/chatting/send_text.py

API Reference

All endpoints are documented with type hints. For the complete list of endpoints and their parameters, see the Bridge documentation.

Main Endpoints

• Sessions: list_sessions, get_session, get_session_me
• Profile: get_my_profile, set_profile_name, set_profile_status, set_profile_picture, delete_profile_picture
• Chatting: send_message (generic endpoint for all types: text, image, file, voice, video, poll, location, contact-vcard, forward, list), reaction, start_typing, stop_typing
• Status: status_text, status_image, status_voice, status_video, status_delete
• Chats: chats_get, chats_overview_get, chats_overview_post, chats_get_messages, chats_read_messages, chats_get_message, chats_delete_message, chats_edit_message, chats_pin_message, chats_unpin_message
• Contacts: contacts_get_all, contacts_get_basic, contacts_check_exists, contacts_profile_picture, contacts_get_about, contacts_block, contacts_unblock, contacts_upsert
• Bulk: list_bulk_jobs, pause_bulk_job, resume_bulk_job, cancel_bulk_job, bulk_stop_campaign, bulk_resume_campaign, bulk_availability

Contributing

Contributions are welcome. Please:

1. Fork the repository
2. Create a branch for your feature (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see LICENSE for more details.

Support

• API Docs (official documentation): https://notibuzz.com/api-docs
• Request a DEMO: notibuzz.com — request a platform demonstration
• Issues: GitHub Issues
• Documentation: README

Changelog

See CHANGELOG.md for detailed version history.