You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CHANGELOG.md
+1Lines changed: 1 addition & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -26,6 +26,7 @@ All notable changes to the **Sinch Python SDK** are documented in this file.
26
26
-**[deprecation notice]**`HTTPTransport.send(endpoint)` is deprecated in favour of `send_request(request_data)`; the legacy method still works for backward compatibility, but will be removed in 3.0 (#156).
27
27
-**[deprecation notice]**`TokenManagerBase.invalidate_expired_token()` and `handle_invalid_token()` (and the `TokenState.EXPIRED` value) are deprecated and will be removed in 3.0, as token renewal now goes through `refresh_auth_token()` (#156).
28
28
-**[tech]** Removed unused GitHub environment secrets from CI workflow and simplified test fixtures to use hardcoded test values (#162).
29
+
-**[doc]** Improve README structure and content(#155).
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.
16
7
17
8
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 [dashboard.sinch.com](https://dashboard.sinch.com).
18
9
19
-
For more information on the Sinch APIs on which this SDK is based, refer to the official [developer documentation portal](https://developers.sinch.com).
10
+
For more information on the SDK, refer to the dedicated [Python SDK documentation](https://developers.sinch.com/docs/sdks/python) section, and for the Sinch APIs on which this SDK is based, refer to the official [developer documentation portal](https://developers.sinch.com).
- Python in one of the supported versions - 3.9, 3.10, 3.11, 3.12, 3.13, 3.14
30
-
- pip
31
-
- Sinch account
31
+
-[Python](https://www.python.org/) in one of the supported versions - [3.9](https://www.python.org/downloads/release/python-390/), [3.10](https://www.python.org/downloads/release/python-3100/), [3.11](https://www.python.org/downloads/release/python-3110/), [3.12](https://www.python.org/downloads/release/python-3120/), [3.13](https://www.python.org/downloads/release/python-3130/), [3.14](https://www.python.org/downloads/release/python-3140/)
32
+
-[pip](https://pip.pypa.io/en/stable/)
33
+
-[Sinch account](https://dashboard.sinch.com/)
34
+
35
+
> **Warning**:
36
+
> 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.
32
37
33
38
## Installation
34
39
35
-
You can install this package by typing:
36
-
`pip install sinch`
40
+
Run the following command to install the SDK:
41
+
42
+
```bash
43
+
pip install sinch
44
+
```
45
+
46
+
47
+
## Supported APIs
37
48
38
-
## Products
39
49
40
-
The Sinch client provides access to the following Sinch products:
> **Note:** The SMS API is end-of-sale. New integrations should use the [Conversation API](https://developers.sinch.com/docs/conversation/) instead, which supports SMS and many other channels.
44
58
45
59
46
60
## Getting started
47
61
48
62
49
63
### Client initialization
50
64
51
-
To establish a connection with the Sinch backend, you must provide credentials based on the API you intend to use.
52
-
For security best practices, avoid hardcoding credentials — retrieve them from environment variables instead.
53
-
54
-
> **Note:**`sms_region` and `conversation_region` no longer have defaults and **must** be set before
55
-
> calling those APIs—omitting them will cause a runtime error. See [MIGRATION_GUIDE.md](MIGRATION_GUIDE.md) for details.
65
+
To start using the SDK, initialize the main client class. This client gives you access to all the SDK services:
56
66
67
+
```python
68
+
import os
69
+
from sinch import SinchClient
57
70
58
-
#### SMS API
71
+
# Warning: not all APIs support project authentication. Check the section for each API before using this snippet.
59
72
60
-
The SMS API supports two authentication methods. `sms_region` is required for both and has no default.
73
+
sinch_client = SinchClient(
74
+
project_id=os.environ["SINCH_PROJECT_ID"],
75
+
key_id=os.environ["SINCH_KEY_ID"],
76
+
key_secret=os.environ["SINCH_KEY_SECRET"],
77
+
)
78
+
```
61
79
62
-
**Project auth (OAuth2)**
80
+
Get `project_id`, `key_id` and `key_secret` from the [Access keys](https://dashboard.sinch.com/settings/access-keys) page in your Sinch dashboard (`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.
63
81
64
-
The SDK automatically exchanges your key ID and key secret for a short-lived OAuth2 token and refreshes it automatically on expiry.
65
-
Supported regions: `us`, `eu`, `br`.
82
+
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.
66
83
67
-
In your [Account dashboard](https://dashboard.sinch.com/settings/access-keys), you will find your `projectId` and access keys composed of pairs of `keyId` / `keySecret`.
84
+
### Conversation API
68
85
69
-
> **Note:** the `keySecret`is visible only when you create the Access Key. Store it safely and create a new Access Key if you have lost it.
86
+
The Conversation API is regionalized. To use this API, the `conversation_region` parameter is required:
70
87
71
88
```python
72
-
from sinch import SinchClient
73
-
74
89
sinch_client = SinchClient(
75
-
project_id="project_id",
76
-
key_id="key_id",
77
-
key_secret="key_secret",
78
-
sms_region="us"
90
+
project_id=os.environ["SINCH_PROJECT_ID"],
91
+
key_id=os.environ["SINCH_KEY_ID"],
92
+
key_secret=os.environ["SINCH_KEY_SECRET"],
93
+
conversation_region="eu",
79
94
)
80
95
```
81
96
82
-
**Service Plan ID auth (legacy)**
83
-
84
-
Uses a static bearer token that never expires.
85
-
Support all regions: `us`, `eu`, `br`, `ca`, `au`.
97
+
#### Sinch Events
86
98
87
-
In your [Service APIs dashboard](https://dashboard.sinch.com/sms/api/services), you will find your `servicePlanId`and `apiToken` (bearer token).
99
+
The Conversation API delivers asynchronous Sinch Events to the Event Destination URL you configure for your app in the [Conversation dashboard](https://dashboard.sinch.com/convapi/apps). `validate_authentication_header` confirms a request comes from Sinch and `parse_event` turns its payload into a typed event object; `headers`and `raw_body` are the incoming request's headers and raw body:
`SINCH_EVENT_SECRET` is optional and set per app in the [Conversation dashboard](https://dashboard.sinch.com/convapi/apps). `parse_event` works without validating the request, but then its origin can't be verified, so calling `validate_authentication_header` (which returns `True`/`False`) is recommended in production.
108
+
109
+
You can find a complete example in [examples/sinch_events/conversation_api](./examples/sinch_events/conversation_api).
110
+
111
+
### SMS API
112
+
113
+
> **Warning:** the SMS API is end-of-sale. For new integrations, prefer the [Conversation API](#conversation-api).
114
+
115
+
The SMS API is regionalized: set `sms_region` to the region where your SMS account is hosted. The accepted values are `us`, `eu`, `au`, `br` and `ca`, and the region also determines which credentials you can use:
91
116
117
+
-**Project access keys** — available only in the `us` and `eu` regions. Use the same `project_id`, `key_id` and `key_secret` as the common client, plus `sms_region`:
118
+
119
+
```python
92
120
sinch_client = SinchClient(
93
-
service_plan_id="service_plan_id",
94
-
sms_api_token="api_token",
95
-
sms_region="us"
121
+
project_id=os.environ["SINCH_PROJECT_ID"],
122
+
key_id=os.environ["SINCH_KEY_ID"],
123
+
key_secret=os.environ["SINCH_KEY_SECRET"],
124
+
sms_region="us",
96
125
)
97
126
```
98
127
99
-
#### Conversation API - Project auth (OAuth2)
128
+
> **SMS authentication for new projects**
129
+
>
130
+
> Projects created after the SMS API end-of-sale (`15/04/26`) cannot use
131
+
> project access keys — the SMS API requests return `401 Unauthorized`.
132
+
>
133
+
> If you encounter this issue, consider the following options:
134
+
>
135
+
> 1. Use service plan credentials (`service_plan_id` + `sms_api_token`)
136
+
> 2. Use the Conversation API, which works with project access keys.
137
+
> 3. Contact your account manager
100
138
101
-
`conversation_region` is required and has no default.
102
-
Supported regions: `us`, `eu`, `br`.
103
139
104
-
>**Why region matters:**The Conversation API stores and routes data within the selected region for regulatory compliance. Choose the region that matches your data residency requirements.
140
+
-**Service plan**— available in all regions (`us`, `eu`, `au`, `br`, `ca`). Use a `service_plan_id` and `sms_api_token`, both available on the [Service APIs dashboard](https://dashboard.sinch.com/sms/api/services):
> **SMS integration note:** If you also use the SMS API, `sms_region` and `conversation_region`**must match**. Mismatched regions will cause delivery failures.
150
+
> **Note:** if you use both the SMS and the [Conversation API](#conversation-api)
151
+
> from the same client, set `sms_region` and `conversation_region` to the same
152
+
> region. Mismatched regions cause delivery failures.
118
153
119
-
#### Other APIs - Project auth (OAuth2)
154
+
#### Sinch Events
120
155
121
-
These APIs are not regionalized and use project-based auth.
156
+
The SMS API delivers asynchronous Sinch Events to an Event Destination, whose URL is set per batch with the `event_destination_target` parameter on the send, update and replace operations (for example `sinch_client.sms.batches.send_sms`). `validate_authentication_header` confirms a request comes from Sinch and `parse_event` turns its payload into a typed event object; `headers` and `raw_body` are the incoming request's headers and raw body:
Signature authentication for SMS events must be enabled for your account by your account manager; until then the signature headers are absent and `parse_event` can be used on its own. See the [SMS events documentation](https://developers.sinch.com/docs/sms/api-reference/sms/tag/Webhooks/#tag/Webhooks/section/Callbacks).
165
+
166
+
You can find a complete example in [examples/sinch_events/sms_api](./examples/sinch_events/sms_api).
167
+
168
+
### Numbers API
169
+
170
+
The Numbers API needs no extra parameters, use the [common client](#client-initialization) based in project authentication shown above.
171
+
172
+
#### Sinch Events
173
+
174
+
The Numbers API delivers asynchronous Sinch Events to the Event Destination you configure through `sinch_client.numbers.event_destinations`. `validate_authentication_header` confirms a request comes from Sinch and `parse_event` turns its payload into a typed event object; `headers` and `raw_body` are the incoming request's headers and raw body:
`SINCH_EVENT_SECRET` is the value configured on the Event Destination. `parse_event` works without validating the request, but then its origin can't be verified, so calling `validate_authentication_header` is recommended in production.
134
183
135
-
Logging configuration for this SDK utilizes following hierarchy:
136
-
1. If no configuration was provided via `logger_name` or `logger` configurable, SDK will inherit configuration from the root logger with the `Sinch` prefix.
137
-
2. If `logger_name` configurable was provided, SDK will use logger related to that name. For example: `myapp.sinch` will inherit configuration from the `myapp` logger.
138
-
3. If `logger` (logger instance) configurable was provided, SDK will use that particular logger for all its logging operations.
184
+
You can find a complete example in [examples/sinch_events/numbers_api](./examples/sinch_events/numbers_api).
139
185
140
-
If all logging returned by this SDK needs to be disabled, usage of `NullHandler` provided by the standard `logging` module is advised.
186
+
### Number Lookup API
187
+
188
+
The Number Lookup API needs no extra parameters, use the [common client](#client-initialization) based in project authentication shown above.
141
189
142
190
143
-
144
-
## Sample apps
145
191
146
-
Usage example of the Numbers API via [`VirtualNumbers`](sinch/domains/numbers/virtual_numbers.py) on the client (`sinch_client.numbers`)—`list()` returns your project’s active virtual numbers:
192
+
### Your First Request
193
+
194
+
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:
"text": "[Python SDK: Conversation Message] Sample text message",
202
+
},
203
+
},
204
+
recipient_identities=[
205
+
{
206
+
"channel": "SMS",
207
+
"identity": "RECIPIENT_PHONE_NUMBER",
208
+
}
209
+
],
152
210
)
153
-
for active_number in paginator.iterator():
154
-
print(active_number)
211
+
212
+
print(f"Successfully sent message.\n{response}")
155
213
```
156
214
157
-
Returned values are [Pydantic](https://docs.pydantic.dev/) model instances (for example [`ActiveNumber`](sinch/domains/numbers/models/v1/response/active_number.py)), including fields such as `phone_number`, `region_code`, `type`, and `capabilities`.
215
+
## Logging
216
+
217
+
Logging configuration for this SDK utilizes following hierarchy:
218
+
1. If no configuration was provided via `logger_name` or `logger` configurable, SDK will inherit configuration from the root logger with the `Sinch` prefix.
219
+
2. If `logger_name` configurable was provided, SDK will use logger related to that name. For example: `myapp.sinch` will inherit configuration from the `myapp` logger.
220
+
3. If `logger` (logger instance) configurable was provided, SDK will use that particular logger for all its logging operations.
158
221
159
-
More examples live under [examples/snippets](examples/snippets) on the `main` branch.
222
+
If all logging returned by this SDK needs to be disabled, usage of `NullHandler` provided by the standard `logging` module is advised.
160
223
161
-
###Handling exceptions
224
+
## Handling exceptions
162
225
163
226
Each API throws a custom, API related exception for an unsuccessful backed call.
164
227
@@ -178,7 +241,6 @@ except NumbersException as err:
178
241
179
242
For handling all possible exceptions thrown by this SDK use `SinchException` (superclass of all Sinch exceptions) from `sinch.core.exceptions`.
180
243
181
-
182
244
## Custom HTTP client implementation
183
245
184
246
By default, the HTTP implementation uses the `requests` library.
0 commit comments