A clean and lightweight Python SDK for Termii — send SMS, WhatsApp messages, manage phonebooks, contacts, campaigns, and more.
pip install python-termiiInitialize the client with your API key and base URL. Both can be passed directly or loaded from environment variables.
from termii_py import TermiiClient
# Pass credentials directly
client = TermiiClient(api_key="YOUR_API_KEY", base_url="YOUR_BASE_URL")
# Or set environment variables and call with no arguments
client = TermiiClient()Using a .env file (recommended):
TERMII_API_KEY=your_api_key
TERMII_BASE_URL=your_base_urlfrom termii_py import TermiiClient
client = TermiiClient()Get your API key and base URL from your Termii dashboard. A
ClientConfigErroris raised if either value is missing.
All services are available as attributes on the TermiiClient instance.
Fetch sender IDs — optionally filter by name or status:
# Fetch all
client.sender_id.fetch_id()
# Filter by name or status
client.sender_id.fetch_id(name="MyBrand", status="approved")Request a new sender ID:
client.sender_id.request_id(
sender_id="MyBrand",
usecase="Transactional alerts for order confirmations",
company="Acme Ltd"
)Send a single SMS:
client.message.send_message(
sent_to="2348012345678",
sent_from="MyBrand",
message="Your order has been confirmed.",
channel="generic", # "generic", "dnd", or "voice"
type="plain"
)For voice channel,
typemust be"voice". WhatsApp messages must usesend_whatsapp_message().
Send a WhatsApp message:
# Text only
client.message.send_whatsapp_message(
sent_to="2348012345678",
sent_from="MyBrand",
message="Hello! Your appointment is confirmed."
)
# With media attachment
client.message.send_whatsapp_message(
sent_to="2348012345678",
sent_from="MyBrand",
message="Here is your receipt.",
url="https://example.com/receipt.pdf",
caption="Receipt - March 2025"
)Send a bulk SMS:
client.message.send_bulk_message(
sent_to=["2348012345678", "2349087654321"],
sent_from="MyBrand",
message="Our sale starts today!",
channel="generic", # "generic" or "dnd" only
type="plain"
)Voice and WhatsApp are not supported for bulk messaging.
Send a message directly to a phone number without a sender ID:
client.number.send_message(
sent_to="2348012345678",
message="Your verification code is 123456."
)Send a message using a pre-approved WhatsApp template:
# Text template
client.template.send_message(
sent_to="2348012345678",
device_id="your-device-id",
template_id="your-template-id",
data={"studname": "Victor", "average": "30"}
)
# Media template (url and caption must be provided together)
client.template.send_message(
sent_to="2348012345678",
device_id="your-device-id",
template_id="your-template-id",
data={"name": "Victor"},
url="https://example.com/document.pdf",
caption="Course Result"
)
device_idis found on the Manage Device page of your Termii dashboard.
Fetch all phonebooks:
client.phonebook.fetch_phonebooks()Create a phonebook:
client.phonebook.create_phonebooks(
phonebook_name="Newsletter Subscribers",
description="Users opted in for weekly updates"
)Update a phonebook:
client.phonebook.update_phonebook(
phonebook_id="abc123",
phonebook_name="VIP Customers",
description="High-value customer segment"
)Delete a phonebook:
client.phonebook.delete_phonebook(phonebook_id="abc123")Fetch contacts in a phonebook:
client.contact.fetch_contacts(phonebook_id="abc123")Add a single contact:
client.contact.create_contact(
phonebook_id="abc123",
phone_number="8012345678",
country_code="234", # No leading "+"
first_name="Ada",
last_name="Obi",
email_address="ada@example.com",
company="Acme Ltd"
)Add multiple contacts via CSV upload:
client.contact.create_multiple_contacts(
phonebook_id="abc123",
country_code="234", # No leading "+"
file_path="/path/to/contacts.csv"
)Delete all contacts in a phonebook:
client.contact.delete_contact(phonebook_id="abc123")
⚠️ delete_contactremoves all contacts in the specified phonebook. Use with caution.
Send a campaign:
# Send immediately
client.campaign.send_campaign(
country_code="234", # No leading "+"
sender_id="MyBrand", # 3–11 characters
message="Big sale — ends tonight!",
message_type="plain", # "plain" or "unicode"
phonebook_id="abc123",
enable_link_tracking=False,
campaign_type="promotional",
schedule_sms_status="regular", # "regular" or "scheduled"
channel="dnd" # "dnd" or "generic"
)
# Schedule for later
client.campaign.send_campaign(
country_code="234",
sender_id="MyBrand",
message="Your monthly statement is ready.",
message_type="plain",
phonebook_id="abc123",
enable_link_tracking=True,
campaign_type="transactional",
schedule_sms_status="scheduled",
schedule_time="2025-12-31T23:59:00Z", # Required when schedule_sms_status is "scheduled"
channel="dnd"
)Fetch all campaigns:
client.campaign.fetch_campaigns()Fetch a specific campaign's history:
client.campaign.fetch_campaign_history(campaign_id="camp_xyz")Retry a failed campaign:
client.campaign.retry_campaign(campaign_id="camp_xyz")The SDK validates inputs before making any network call and raises ValueError for invalid parameters. Wrap calls
accordingly:
try:
response = client.message.send_message(
sent_to="2348012345678",
sent_from="MyBrand",
message="Hello!",
channel="generic",
type="plain"
)
except ValueError as e:
print(f"Validation error: {e}")
except Exception as e:
print(f"Unexpected error: {e}")Contributions are welcome!
- Fork the repository
- Create a feature branch:
git checkout -b feature/your-feature - Commit your changes:
git commit -m "feat: describe your change" - Push:
git push origin feature/your-feature - Open a Pull Request
Please open an issue first for significant changes.
This project is licensed under the MIT License.
Built by Samuel Doghor · Powered by the Termii API