{"templateId":"../../../@theme/Templates/SideBySide.tsx","sharedDataIds":{"sidebar":"sidebar-docs/sdks/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["split","partial"]},"type":"markdown"},"seo":{"title":"Python SDK Reference Docs | Sinch","siteUrl":"https://developers.sinch.com","llmstxt":{"title":"Sinch Developer Documentation","description":"LLMs.txt containing a map of all the documentation files for Sinch.","sections":[{"title":"Numbers API","description":"The Numbers API enables you to search for, view, and activate numbers. It's considered a precursor to other APIs in the Sinch product family. The numbers API can be used in tandem with any of our APIs that perform messaging or calling.","includeFiles":["docs/numbers/**/*.md","docs/numbers/**/*.yaml"],"excludeFiles":["docs/numbers/index.md"]},{"title":"Conversation API","description":"Send and receive messages globally on many popular channels with ease and confidence when using Sinch's Conversation API. Conversation API is the preferred API for sending mobile messages on SMS and other social channels with Sinch. It is a simple API with unified error messages, consistent request payloads, and common webhook payloads that are channel-agnostic.","includeFiles":["docs/conversation/**/*.md","docs/conversation/**/*.yaml"],"excludeFiles":["docs/conversation/index.md"]},{"title":"Voice API","description":"The Voice API works as a big telephony switch. The Voice API handles incoming phone calls (also known as incoming call “legs”), sets up outgoing phone calls (or outgoing call “legs”), and bridges the two. The incoming call leg may come in over a data connection (from a smartphone or web application using the Sinch SDKs) or through a local phone number (from the PSTN network). Similarly, the outgoing call leg can be over data (to another smartphone or web application using the Sinch SDKs) or the PSTN network.","includeFiles":["docs/voice/**/*.md","docs/voice/**/*.yaml"],"excludeFiles":["docs/voice/index.md"]},{"title":"Verification API","description":"The Verification API is a platform for phone number verification. It consists of the API and different software development kits (the Sinch SDKs) that you integrate with your smartphone or web application and cloud based back-end services. Together they enable SMS, Flashcall, Phone Call and Data verification in your application.","includeFiles":["docs/verification/**/*.md","docs/verification/**/*.yaml"],"excludeFiles":["docs/verification/index.md"]},{"title":"Provisioning API","description":"Provisioning API allows you to programmatically set up your senders, accounts and templates on your favorite messaging platforms on the Conversation API. For now, you can create your first WhatsApp channel through Meta's Embedded sign up, you can configure your first SMS App and configure your webhooks. As development continues, we will be adding the most commonly used channels.","includeFiles":["docs/provisioning-api/**/*.md","docs/provisioning-api/**/*.json"],"excludeFiles":["docs/provisioning-api/index.md"]},{"title":"Elastic SIP Trunking API","description":"With Elastic SIP Trunking you can create and manage your SIP trunks and phone numbers programmatically.","includeFiles":["docs/est/**/*.md","docs/est/**/*.yaml"],"excludeFiles":["docs/est/index.md"]},{"title":"Fax API","description":"Send and receive HIPAA compliant faxes on our modern fax platform using our developer-friendly API.","includeFiles":["docs/fax/**/*.md","docs/fax/**/*.yaml"],"excludeFiles":["docs/fax/index.md"]},{"title":"In-app Voice and Video SDK","description":"The In-app Voice and Video SDK enables you to add voice and video calling capabilities directly into your mobile or web application using the Sinch SDKs.","includeFiles":["docs/in-app-calling/**/*.md"],"excludeFiles":["docs/in-app-calling/index.md"]},{"title":"Number Lookup API","description":"The Number Lookup API is designed to provide in-depth information about phone numbers, helping enterprises enhance their communication strategies and prevent fraud. By identifying the type of phone line (for example, mobile, landline, VoIP) and the associated carrier, the API allows businesses to optimize routing, reduce unnecessary costs, and improve customer engagement.","includeFiles":["docs/number-lookup-api-v2/**/*.md","docs/number-lookup-api-v2/**/*.yaml"],"excludeFiles":["docs/number-lookup-api-v2/index.md"]},{"title":"Functions","description":"Serverless compute for voice and messaging. Deploy your code and Sinch routes live calls and messages to it — no infrastructure to run.","includeFiles":["docs/functions/functions/**/*.md","docs/functions/concepts/**/*.md","docs/functions/reference/**/*.md"],"excludeFiles":["docs/functions/functions/index.md"]},{"title":"CLI","description":"One command line for every Sinch API and the full Functions lifecycle — scaffold, run locally, deploy, and manage.","includeFiles":["docs/functions/cli/**/*.md"],"excludeFiles":["docs/functions/cli/index.md"]}]},"description":"See all versions of the Sinch Python SDK reference documentation."},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Split","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"sinch-python-sdk","__idx":0},"children":["Sinch Python SDK"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://www.python.org/"},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"https://img.shields.io/badge/python-blue.svg","alt":"Python"},"children":[]}]}," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://pypi.org/project/sinch/"},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"https://img.shields.io/pypi/v/sinch?label=sinch&labelColor=FFC658","alt":"Latest Release"},"children":[]}]}," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/sinch/sinch-sdk-python/blob/main/LICENSE"},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"https://img.shields.io/badge/License-Apache_2.0-blue.svg","alt":"License"},"children":[]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here you'll find documentation related to the Sinch Python SDK, including how to install it, initialize it, and start developing Python code using Sinch services."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To use Sinch services, you'll need a Sinch account and access keys. You can sign up for an account and create access keys at ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://dashboard.sinch.com"},"children":["dashboard.sinch.com"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"table-of-contents","__idx":1},"children":["Table of contents:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#prerequisites"},"children":["Prerequisites"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#documentation"},"children":["Documentation"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#installation"},"children":["Installation"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#supported-apis"},"children":["Supported APIs"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#getting-started"},"children":["Getting started"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#logging"},"children":["Logging"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#handling-exceptions"},"children":["Handling Exceptions"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#custom-http-client-implementation"},"children":["Custom HTTP client implementation"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#third-party-dependencies"},"children":["Third-party dependencies"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#examples"},"children":["Examples"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#changelog--migration"},"children":["Changelog and Migration"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#license"},"children":["License"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#contact"},"children":["Contact"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":2},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://www.python.org/"},"children":["Python"]}," in one of the supported versions - ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://www.python.org/downloads/release/python-390/"},"children":["3.9"]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://www.python.org/downloads/release/python-3100/"},"children":["3.10"]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://www.python.org/downloads/release/python-3110/"},"children":["3.11"]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://www.python.org/downloads/release/python-3120/"},"children":["3.12"]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://www.python.org/downloads/release/python-3130/"},"children":["3.13"]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://www.python.org/downloads/release/python-3140/"},"children":["3.14"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://pip.pypa.io/en/stable/"},"children":["pip"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://dashboard.sinch.com/"},"children":["Sinch account"]}]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Warning"]},":"," ","This SDK is intended for server-side (backend) use only. Do not use it in front-end or client-side applications (web, mobile, or desktop), regardless of language or framework. Doing so can expose your Sinch credentials to end-users."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"documentation","__idx":3},"children":["Documentation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more information on the SDK, refer to the dedicated ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://developers.sinch.com/docs/sdks/python"},"children":["Python SDK documentation"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For the SDK's programmatic API surface, see the online ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://developers.sinch.com/sdk/sinch-sdk-python/latest"},"children":["SDK reference"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For broader Sinch product documentation, including the underlying REST APIs, visit the official ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://developers.sinch.com/"},"children":["Sinch developer portal"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"installation","__idx":4},"children":["Installation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Run the following command to install the SDK:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"pip install sinch\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"supported-apis","__idx":5},"children":["Supported APIs"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"API Category"},"children":["API Category"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"API Name"},"children":["API Name"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Messaging"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://developers.sinch.com/docs/conversation/"},"children":["Conversation API"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://developers.sinch.com/docs/sms/"},"children":["SMS API"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Numbers"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://developers.sinch.com/docs/numbers/"},"children":["Numbers API"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Verification"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://developers.sinch.com/docs/number-lookup/"},"children":["Number Lookup API"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note:"]}," The SMS API is end-of-sale. New integrations should use the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://developers.sinch.com/docs/conversation/"},"children":["Conversation API"]}," instead, which supports SMS and many other channels."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"getting-started","__idx":6},"children":["Getting started"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"client-initialization","__idx":7},"children":["Client initialization"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To start using the SDK, initialize the main client class. This client gives you access to all the SDK services:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"import os\nfrom sinch import SinchClient\n\n# Warning: not all APIs support project authentication. Check the section for each API before using this snippet.\n\nsinch_client = SinchClient(\n    project_id=os.environ[\"SINCH_PROJECT_ID\"],\n    key_id=os.environ[\"SINCH_KEY_ID\"],\n    key_secret=os.environ[\"SINCH_KEY_SECRET\"],\n)\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Get ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["project_id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["key_id"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["key_secret"]}," from the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://dashboard.sinch.com/settings/access-keys"},"children":["Access keys"]}," page in your Sinch dashboard (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["key_secret"]}," is shown only once, at creation time). It's highly recommended to not hardcode these credentials: load them from environment variables for local development, and from a secret manager in production."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This snippet is the common starting point for every API. Some APIs have a different initialization or need extra parameters (for example, a region), see the section for each API."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"conversation-api","__idx":8},"children":["Conversation API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Conversation API is regionalized. To use this API, the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["conversation_region"]}," parameter is required:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"sinch_client = SinchClient(\n    project_id=os.environ[\"SINCH_PROJECT_ID\"],\n    key_id=os.environ[\"SINCH_KEY_ID\"],\n    key_secret=os.environ[\"SINCH_KEY_SECRET\"],\n    conversation_region=\"eu\",\n)\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"sinch-events","__idx":9},"children":["Sinch Events"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Conversation API delivers asynchronous Sinch Events to the Event Destination URL you configure for your app in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://dashboard.sinch.com/convapi/apps"},"children":["Conversation dashboard"]},". ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validate_authentication_header"]}," confirms a request comes from Sinch and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["parse_event"]}," turns its payload into a typed event object; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["headers"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["raw_body"]}," are the incoming request's headers and raw body:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"sinch_events = sinch_client.conversation.sinch_events(SINCH_EVENT_SECRET)\nis_valid = sinch_events.validate_authentication_header(headers=headers, json_payload=raw_body)\nevent = sinch_events.parse_event(raw_body, headers)\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SINCH_EVENT_SECRET"]}," is optional and set per app in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://dashboard.sinch.com/convapi/apps"},"children":["Conversation dashboard"]},". ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["parse_event"]}," works without validating the request, but then its origin can't be verified, so calling ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validate_authentication_header"]}," (which returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["True"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["False"]},") is recommended in production."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can find a complete example in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/sinch/sinch-sdk-python/blob/main/examples/sinch_events/conversation_api"},"children":["examples/sinch_events/conversation_api"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"sms-api","__idx":10},"children":["SMS API"]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Warning:"]}," the SMS API is end-of-sale. For new integrations, prefer the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#conversation-api"},"children":["Conversation API"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The SMS API is regionalized: set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sms_region"]}," to the region where your SMS account is hosted. The accepted values are ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["us"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eu"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["au"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["br"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ca"]},", and the region also determines which credentials you can use:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Project access keys"]}," — available only in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["us"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eu"]}," regions. Use the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["project_id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["key_id"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["key_secret"]}," as the common client, plus ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sms_region"]},":"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"sinch_client = SinchClient(\n    project_id=os.environ[\"SINCH_PROJECT_ID\"],\n    key_id=os.environ[\"SINCH_KEY_ID\"],\n    key_secret=os.environ[\"SINCH_KEY_SECRET\"],\n    sms_region=\"us\",\n)\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["SMS authentication for new projects"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Projects created after the SMS API end-of-sale (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["15/04/26"]},") cannot use"," ","project access keys — the SMS API requests return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401 Unauthorized"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you encounter this issue, consider the following options:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use service plan credentials (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["service_plan_id"]}," + ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sms_api_token"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use the Conversation API, which works with project access keys."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Contact your account manager"]}]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Service plan"]}," — available in all regions (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["us"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eu"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["au"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["br"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ca"]},"). Use a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["service_plan_id"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sms_api_token"]},", both available on the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://dashboard.sinch.com/sms/api/services"},"children":["Service APIs dashboard"]},":"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"sinch_client = SinchClient(\n    service_plan_id=os.environ[\"SINCH_SERVICE_PLAN_ID\"],\n    sms_api_token=os.environ[\"SINCH_SMS_API_TOKEN\"],\n    sms_region=\"us\",\n)\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note:"]}," if you use both the SMS and the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#conversation-api"},"children":["Conversation API"]}," ","from the same client, set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sms_region"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["conversation_region"]}," to the same"," ","region. Mismatched regions cause delivery failures."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"sinch-events-1","__idx":11},"children":["Sinch Events"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The SMS API delivers asynchronous Sinch Events to an Event Destination, whose URL is set per batch with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["event_destination_target"]}," parameter on the send, update and replace operations (for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sinch_client.sms.batches.send_sms"]},"). ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validate_authentication_header"]}," confirms a request comes from Sinch and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["parse_event"]}," turns its payload into a typed event object; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["headers"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["raw_body"]}," are the incoming request's headers and raw body:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"sinch_events = sinch_client.sms.sinch_events(SINCH_EVENT_SECRET)\nis_valid = sinch_events.validate_authentication_header(headers=headers, json_payload=raw_body)\nevent = sinch_events.parse_event(raw_body, headers)\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Signature authentication for SMS events must be enabled for your account by your account manager; until then the signature headers are absent and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["parse_event"]}," can be used on its own. See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://developers.sinch.com/docs/sms/api-reference/sms/tag/Webhooks/#tag/Webhooks/section/Callbacks"},"children":["SMS events documentation"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can find a complete example in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/sinch/sinch-sdk-python/blob/main/examples/sinch_events/sms_api"},"children":["examples/sinch_events/sms_api"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"numbers-api","__idx":12},"children":["Numbers API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Numbers API needs no extra parameters, use the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#client-initialization"},"children":["common client"]}," based in project authentication shown above."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"sinch-events-2","__idx":13},"children":["Sinch Events"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Numbers API delivers asynchronous Sinch Events to the Event Destination you configure through ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sinch_client.numbers.event_destinations"]},". ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validate_authentication_header"]}," confirms a request comes from Sinch and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["parse_event"]}," turns its payload into a typed event object; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["headers"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["raw_body"]}," are the incoming request's headers and raw body:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"sinch_events = sinch_client.numbers.sinch_events(SINCH_EVENT_SECRET)\nis_valid = sinch_events.validate_authentication_header(headers=headers, json_payload=raw_body)\nevent = sinch_events.parse_event(raw_body, headers)\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SINCH_EVENT_SECRET"]}," is the value configured on the Event Destination. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["parse_event"]}," works without validating the request, but then its origin can't be verified, so calling ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validate_authentication_header"]}," is recommended in production."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can find a complete example in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/sinch/sinch-sdk-python/blob/main/examples/sinch_events/numbers_api"},"children":["examples/sinch_events/numbers_api"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"number-lookup-api","__idx":14},"children":["Number Lookup API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Number Lookup API needs no extra parameters, use the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#client-initialization"},"children":["common client"]}," based in project authentication shown above."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"your-first-request","__idx":15},"children":["Your First Request"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once your client is configured, you can send your first message. The example below uses the Conversation API to send a simple text message over SMS. Replace CONVERSATION_APP_ID with your app ID and RECIPIENT_PHONE_NUMBER with the recipient's phone number:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"response = sinch_client.conversation.messages.send(\n    app_id=\"CONVERSATION_APP_ID\",\n    message={\n        \"text_message\": {\n            \"text\": \"[Python SDK: Conversation Message] Sample text message\",\n        },\n    },\n    recipient_identities=[\n        {\n            \"channel\": \"SMS\",\n            \"identity\": \"RECIPIENT_PHONE_NUMBER\",\n        }\n    ],\n)\n\nprint(f\"Successfully sent message.\\n{response}\")\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"logging","__idx":16},"children":["Logging"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Logging configuration for this SDK utilizes following hierarchy:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If no configuration was provided via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["logger_name"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["logger"]}," configurable, SDK will inherit configuration from the root logger with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Sinch"]}," prefix."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["logger_name"]}," configurable was provided, SDK will use logger related to that name. For example: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["myapp.sinch"]}," will inherit configuration from the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["myapp"]}," logger."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["logger"]}," (logger instance) configurable was provided, SDK will use that particular logger for all its logging operations."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If all logging returned by this SDK needs to be disabled, usage of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NullHandler"]}," provided by the standard ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["logging"]}," module is advised."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"handling-exceptions","__idx":17},"children":["Handling exceptions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each API throws a custom, API related exception for an unsuccessful backed call."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example for Numbers API:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"from sinch.domains.numbers.api.v1.exceptions import NumbersException\n\ntry:\n    paginator = sinch_client.numbers.list(\n        region_code=\"US\",\n        number_type=\"LOCAL\",\n    )\nexcept NumbersException as err:\n    pass\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For handling all possible exceptions thrown by this SDK use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SinchException"]}," (superclass of all Sinch exceptions) from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sinch.core.exceptions"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"custom-http-client-implementation","__idx":18},"children":["Custom HTTP client implementation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["By default, the HTTP implementation uses the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["requests"]}," library."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To use a custom HTTP client, assign your transport to the client's configuration after initialization."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Custom transports must extend ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["HTTPTransport"]}," and implement the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["send"]}," method. The base class provides ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["prepare_request"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["authenticate"]}," helpers, and handles OAuth token refresh automatically."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example replaces the default ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["requests"]}," backend with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["httpx"]}," and routes traffic through an authenticated proxy:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"import httpx\nfrom sinch import SinchClient\nfrom sinch.core.ports.http_transport import HTTPTransport\nfrom sinch.core.models.http_request import HttpRequest\nfrom sinch.core.models.http_response import HTTPResponse\n\n\nclass MyHTTPImplementation(HTTPTransport):\n    def __init__(self, sinch, proxy_url, proxy_user, proxy_password):\n        super().__init__(sinch)\n        self.http_client = httpx.Client(\n            proxy=f\"http://{proxy_user}:{proxy_password}@{proxy_url}\"\n        )\n\n    def send_request(self, request_data: HttpRequest) -> HTTPResponse:\n\n        body = request_data.request_body\n        response = self.http_client.request(\n            method=request_data.http_method,\n            url=request_data.url,\n            json=body if isinstance(body, dict) else None,\n            content=body if not isinstance(body, dict) else None,\n            auth=request_data.auth,\n            headers=request_data.headers,\n            params=request_data.query_params,\n            timeout=self.sinch.configuration.connection_timeout,\n        )\n        response_body = self.deserialize_json_response(response)\n\n        return HTTPResponse(\n            status_code=response.status_code,\n            body=response_body,\n            headers=dict(response.headers),\n        )\n\n\nsinch_client = SinchClient(\n    key_id=\"key_id\",\n    key_secret=\"key_secret\",\n    project_id=\"some_project\",\n)\nsinch_client.configuration.transport = MyHTTPImplementation(\n    sinch_client,\n    proxy_url=\"proxy.example.com:8080\",\n    proxy_user=\"proxy_user\",\n    proxy_password=\"proxy_password\",\n)\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note:"]}," Asynchronous HTTP clients are not supported. The transport must be"," ","a synchronous implementation."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"third-party-dependencies","__idx":19},"children":["Third-party dependencies"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The SDK relies on the following third-party dependencies:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://requests.readthedocs.io/"},"children":["requests"]},": HTTP client used as the default transport for all API calls."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.pydantic.dev/"},"children":["pydantic"]},": Data validation and serialization for request and response models."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"examples","__idx":20},"children":["Examples"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can find:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["a Python example of each request in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/sinch/sinch-sdk-python/blob/main/examples/snippets"},"children":["examples/snippets"]}," folder."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["getting started guides for specific use cases in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/sinch/sinch-sdk-python/blob/main/examples/getting-started"},"children":["examples/getting-started"]}," folder."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["server-side event handling examples in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/sinch/sinch-sdk-python/blob/main/examples/sinch_events"},"children":["examples/sinch_events"]}," folder."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"changelog--migration","__idx":21},"children":["Changelog & Migration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For information about the latest changes in the SDK, please refer to the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/sinch/sinch-sdk-python/blob/main/CHANGELOG.md"},"children":["CHANGELOG"]}," file"," ","and the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/sinch/sinch-sdk-python/blob/main/MIGRATION_GUIDE.md"},"children":["MIGRATION_GUIDE"]}," for instructions on how to update your code when upgrading to a new major version of the SDK."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"license","__idx":22},"children":["License"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This project is licensed under the Apache License."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/sinch/sinch-sdk-python/blob/main/LICENSE"},"children":["LICENSE"]}," file for the license text."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"contact","__idx":23},"children":["Contact"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Developer Experience engineering team: ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"mailto:team-developer-experience@sinch.com"},"children":["team-developer-experience@sinch.com"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"versions","__idx":24},"children":["Versions"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://developers.sinch.com/sdk/sinch-sdk-python/2.1.0/index.html"},"children":["2.1.0 (latest)"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://developers.sinch.com/sdk/sinch-sdk-python/2.0.1/index.html"},"children":["2.0.1"]}]}]}]}]},"headings":[{"value":"Sinch Python SDK","id":"sinch-python-sdk","depth":1},{"value":"Table of contents:","id":"table-of-contents","depth":2},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"Documentation","id":"documentation","depth":2},{"value":"Installation","id":"installation","depth":2},{"value":"Supported APIs","id":"supported-apis","depth":2},{"value":"Getting started","id":"getting-started","depth":2},{"value":"Client initialization","id":"client-initialization","depth":3},{"value":"Conversation API","id":"conversation-api","depth":3},{"value":"Sinch Events","id":"sinch-events","depth":4},{"value":"SMS API","id":"sms-api","depth":3},{"value":"Sinch Events","id":"sinch-events-1","depth":4},{"value":"Numbers API","id":"numbers-api","depth":3},{"value":"Sinch Events","id":"sinch-events-2","depth":4},{"value":"Number Lookup API","id":"number-lookup-api","depth":3},{"value":"Your First Request","id":"your-first-request","depth":3},{"value":"Logging","id":"logging","depth":2},{"value":"Handling exceptions","id":"handling-exceptions","depth":2},{"value":"Custom HTTP client implementation","id":"custom-http-client-implementation","depth":2},{"value":"Third-party dependencies","id":"third-party-dependencies","depth":2},{"value":"Examples","id":"examples","depth":2},{"value":"Changelog & Migration","id":"changelog--migration","depth":2},{"value":"License","id":"license","depth":2},{"value":"Contact","id":"contact","depth":2},{"value":"Versions","id":"versions","depth":2}],"frontmatter":{"seo":{"title":"Python SDK Reference Docs | Sinch","description":"See all versions of the Sinch Python SDK reference documentation."},"template":"../../../@theme/Templates/SideBySide.tsx"},"lastModified":"2026-07-17T14:30:25.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/sdks/python/sdk-reference-docs","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}