sinch.domains.conversation.api.v1.contacts_apis module

class sinch.domains.conversation.api.v1.contacts_apis.Contacts(sinch)[source]

Bases: BaseConversation

list(

page_size: int | None = None,

page_token: str | None = None,

external_id: str | None = None,

channel: Literal['WHATSAPP', 'RCS', 'SMS', 'MESSENGER', 'VIBERBM', 'MMS', 'INSTAGRAM', 'TELEGRAM', 'KAKAOTALK', 'KAKAOTALKCHAT', 'LINE', 'WECHAT', 'APPLEBC'] | Annotated[str, Strict(strict=True)] | None = None,

identity: str | None = None,

**kwargs,

) → Paginator[ListContactsResponse, ContactResponse][source]

List all contacts in the project. Note that, if a WhatsApp contact is returned, the display_name field of that contact may be populated with the WhatsApp display name (if the name is already stored on the server and the display_name field has not been overwritten by the user).

Parameters:

page_size (Optional[int]) – (optional) The maximum number of contacts to fetch. The server default is 10 and the maximum is 20.
page_token (Optional[str]) – (optional) Next page token previously returned if any.
external_id (Optional[str]) – (optional) Contact identifier in an external system. If used, channel and identity can’t be used.
channel (Optional[ConversationChannelType]) – (optional) Specifies a channel. If set, identity must be set and external_id can’t be used.
identity (Optional[str]) – (optional) If set, channel must be set and external_id can’t be used. Used in conjunction with channel to uniquely identify the specified channel identity.
**kwargs –
Additional parameters for the request.

Returns:

A paginator for iterating through the contacts.

Return type:

Paginator[ListContactsResponse, ContactResponse]

For detailed documentation, visit https://developers.sinch.com/docs/conversation/.

create(channel_identities: ~typing.List[~sinch.domains.conversation.models.v1.types.channel_identity_dict.ChannelIdentityDict], language: ~typing.Literal['AF', 'SQ', 'AR', 'AZ', 'BN', 'BG', 'CA', 'ZH', 'ZH_CN', 'ZH_HK', 'ZH_TW', 'HR', 'CS', 'DA', 'NL', 'EN', 'EN_GB', 'EN_US', 'ET', 'FIL', 'FI', 'FR', 'DE', 'EL', 'GU', 'HA', 'HE', 'HI', 'HU', 'ID', 'GA', 'IT', 'JA', 'KN', 'KK', 'KO', 'LO', 'LV', 'LT', 'MK', 'MS', 'ML', 'MR', 'NB', 'FA', 'PL', 'PT', 'PT_BR', 'PT_PT', 'PA', 'RO', 'RU', 'SR', 'SK', 'SL', 'ES', 'ES_AR', 'ES_ES', 'ES_MX', 'SW', 'SV', 'TA', 'TE', 'TH', 'TR', 'UK', 'UR', 'UZ', 'VI', 'ZU'] | ~typing.Annotated[str, ~pydantic.types.Strict(strict=True)], channel_priority: ~typing.List[~typing.Literal['WHATSAPP', 'RCS', 'SMS', 'MESSENGER', 'VIBERBM', 'MMS', 'INSTAGRAM', 'TELEGRAM', 'KAKAOTALK', 'KAKAOTALKCHAT', 'LINE', 'WECHAT', 'APPLEBC'] | ~typing.Annotated[str, ~pydantic.types.Strict(strict=True)]] | None | ~sinch.core.sentinel.Unset = <sinch.core.sentinel.Unset object>, display_name: str | None | ~sinch.core.sentinel.Unset = <sinch.core.sentinel.Unset object>, email: str | None | ~sinch.core.sentinel.Unset = <sinch.core.sentinel.Unset object>, external_id: str | None | ~sinch.core.sentinel.Unset = <sinch.core.sentinel.Unset object>, metadata: str | None | ~sinch.core.sentinel.Unset = <sinch.core.sentinel.Unset object>, **kwargs) → ContactResponse[source]

Most Conversation API contacts are created automatically when a message is sent to a new recipient. You can also create a new contact manually using this API call.

Parameters:

channel_identities (List[ChannelIdentityDict]) – (required) List of channel identities. Must contain at least one item.
language (ContactLanguageType) – (required) The language of the contact.
channel_priority (UnsetOr[Optional[List[ConversationChannelType]]]) – (optional) List of channels defining the channel priority. The channel at the top of the list is tried first.
display_name (UnsetOr[Optional[str]]) – (optional) The display name. A default ‘Unknown’ will be assigned by the server if left empty.
email (UnsetOr[Optional[str]]) – (optional) Email of the contact.
external_id (UnsetOr[Optional[str]]) – (optional) Contact identifier in an external system.
metadata (UnsetOr[Optional[str]]) – (optional) Metadata associated with the contact. Up to 1024 characters long.
**kwargs –
Additional parameters for the request.

Returns:

The created contact.

Return type:

ContactResponse

For detailed documentation, visit https://developers.sinch.com/docs/conversation/.

get(

contact_id: str,

**kwargs,

) → ContactResponse[source]

Returns a specific contact as specified by the contact ID. Note the following:

If a WhatsApp contact is returned, the display_name field of that contact may be populated with the WhatsApp display name (if the name is already stored on the server and the display_name field has not been overwritten by the user).
If you receive an Inbound Message callback for an MO message on the Instagram channel, the corresponding payload will not include the Instagram username. You may use the contact_id and channel_identity values included in the callback to retrieve the username (detailed in the display_name field) with this operation.

Parameters:

contact_id (str) – (required) The unique ID of the contact to retrieve.
**kwargs –
Additional parameters for the request.

Returns:

The contact details.

Return type:

ContactResponse

For detailed documentation, visit https://developers.sinch.com/docs/conversation/.

delete(contact_id: str, **kwargs) → None[source]

Delete a contact as specified by the contact ID.

Parameters:

contact_id (str) – (required) The unique ID of the contact to delete.
**kwargs –
Additional parameters for the request.

Returns:

None

Return type:

None

For detailed documentation, visit https://developers.sinch.com/docs/conversation/.

update(

contact_id: str,

channel_identities: List[ChannelIdentityDict] | None | Unset = <sinch.core.sentinel.Unset object>,

channel_priority: Literal['WHATSAPP',

'RCS',

'SMS',

'MESSENGER',

'VIBERBM',

'MMS',

'INSTAGRAM',

'TELEGRAM',

'KAKAOTALK',

'KAKAOTALKCHAT',

'LINE',

'WECHAT',

'APPLEBC'] | ~typing.Annotated[str,

~pydantic.types.Strict(strict=True)]] | None | ~sinch.core.sentinel.Unset = <sinch.core.sentinel.Unset object>,

display_name: str | None | Unset = <sinch.core.sentinel.Unset object>,

email: str | None | Unset = <sinch.core.sentinel.Unset object>,

external_id: str | None | Unset = <sinch.core.sentinel.Unset object>,

language: Literal['AF',

'SQ',

'AR',

'AZ',

'BN',

'BG',

'CA',

'ZH',

'ZH_CN',

'ZH_HK',

'ZH_TW',

'HR',

'CS',

'DA',

'NL',

'EN',

'EN_GB',

'EN_US',

'ET',

'FIL',

'FI',

'FR',

'DE',

'EL',

'GU',

'HA',

'HE',

'HI',

'HU',

'ID',

'GA',

'IT',

'JA',

'KN',

'KK',

'KO',

'LO',

'LV',

'LT',

'MK',

'MS',

'ML',

'MR',

'NB',

'FA',

'PL',

'PT',

'PT_BR',

'PT_PT',

'PA',

'RO',

'RU',

'SR',

'SK',

'SL',

'ES',

'ES_AR',

'ES_ES',

'ES_MX',

'SW',

'SV',

'TA',

'TE',

'TH',

'TR',

'UK',

'UR',

'UZ',

'VI',

'ZU'] | ~typing.Annotated[str,

~pydantic.types.Strict(strict=True)] | ~sinch.core.sentinel.Unset = <sinch.core.sentinel.Unset object>,

metadata: str | None | Unset = <sinch.core.sentinel.Unset object>,

**kwargs,

) → ContactResponse[source]

Updates a contact as specified by the contact ID.

Omitted parameters are left untouched on the server; passing None explicitly clears the field.

Parameters:

contact_id (str) – (required) The unique ID of the contact to update.
channel_identities (UnsetOr[Optional[List[ChannelIdentityDict]]]) – (optional) List of channel identities.
channel_priority (UnsetOr[Optional[List[ConversationChannelType]]]) – (optional) List of channels defining the channel priority.
display_name (UnsetOr[Optional[str]]) – (optional) The display name of the contact.
email (UnsetOr[Optional[str]]) – (optional) Email of the contact.
external_id (UnsetOr[Optional[str]]) – (optional) Contact identifier in an external system.
language (UnsetOr[ContactLanguageType]) – (optional) The language of the contact.
metadata (UnsetOr[Optional[str]]) – (optional) Metadata associated with the contact. Up to 1024 characters long.
**kwargs –
Additional parameters for the request.

Returns:

The updated contact.

Return type:

ContactResponse

For detailed documentation, visit https://developers.sinch.com/docs/conversation/.

merge_contact(

destination_id: str,

source_id: str,

strategy: Annotated[str,

~pydantic.types.Strict(strict=True)] | None | ~sinch.core.sentinel.Unset = <sinch.core.sentinel.Unset object>,

**kwargs,

) → ContactResponse[source]

The remaining contact will contain all conversations that the removed contact did. If both contacts had conversations within the same App, messages from the removed contact will be merged into corresponding active conversations in the destination contact. Channel identities will be moved from the source contact to the destination contact only for channels that weren’t present there before. Moved channel identities will be placed at the bottom of the channel priority list. Optional fields from the source contact will be copied only if corresponding fields in the destination contact are empty. The contact being removed cannot be referenced after this call.

Parameters:

destination_id (str) – (required) The unique ID of the contact that should be kept when merging two contacts.
source_id (str) – (required) The ID of the contact that should be removed.
strategy (UnsetOr[Optional[ConversationMergeStrategyType]]) – (optional) The merge strategy to apply. The server default is MERGE.
**kwargs –
Additional parameters for the request.

Returns:

The merged (destination) contact.

Return type:

ContactResponse

For detailed documentation, visit https://developers.sinch.com/docs/conversation/.

get_channel_profile(

app_id: str,

channel: Literal['MESSENGER', 'INSTAGRAM', 'VIBER', 'LINE'] | Annotated[str, Strict(strict=True)],

recipient: RecipientIdentifiedByDict | RecipientContactIdDict,

**kwargs,

) → GetChannelProfileResponse[source]

Get user profile from a specific channel. Only supported on MESSENGER, INSTAGRAM, VIBER and LINE channels. Note that, in order to retrieve a WhatsApp display name, you can use the get or list contact operations instead, which will populate the display_name field of each returned contact with the WhatsApp display name (if the name is already stored on the server and the display_name field has not been overwritten by the user).

Parameters:

app_id (str) – (required) The ID of the app.
channel (GetChannelProfileConversationChannelType) – (required) The channel. Must be one of the supported channels for this operation.
recipient (RecipientDict) – (required) The recipient to retrieve the channel profile for.
**kwargs –
Additional parameters for the request.

Returns:

The channel profile.

Return type:

GetChannelProfileResponse

For detailed documentation, visit https://developers.sinch.com/docs/conversation/.

get_channel_profile_by_contact_id(

app_id: str,

channel: Literal['MESSENGER', 'INSTAGRAM', 'VIBER', 'LINE'] | Annotated[str, Strict(strict=True)],

contact_id: str,

**kwargs,

) → GetChannelProfileResponse[source]

Get user profile from a specific channel. Only supported on MESSENGER, INSTAGRAM, VIBER and LINE channels. Note that, in order to retrieve a WhatsApp display name, you can use the get or list contact operations instead, which will populate the display_name field of each returned contact with the WhatsApp display name (if the name is already stored on the server and the display_name field has not been overwritten by the user).

Parameters:

app_id (str) – (required) The ID of the app.
channel (GetChannelProfileConversationChannelType) – (required) The channel. Must be one of the supported channels for this operation.
contact_id (str) – (required) The contact_id to retrieve the channel profile for.
**kwargs –
Additional parameters for the request.

Returns:

The channel profile.

Return type:

GetChannelProfileResponse

For detailed documentation, visit https://developers.sinch.com/docs/conversation/.

get_channel_profile_by_channel_identity(

app_id: str,

channel: Literal['MESSENGER', 'INSTAGRAM', 'VIBER', 'LINE'] | Annotated[str, Strict(strict=True)],

recipient_identities: List[ChannelRecipientIdentityDict],

**kwargs,

) → GetChannelProfileResponse[source]

Get user profile from a specific channel. Only supported on MESSENGER, INSTAGRAM, VIBER and LINE channels. Note that, in order to retrieve a WhatsApp display name, you can use the get or list contact operations instead, which will populate the display_name field of each returned contact with the WhatsApp display name (if the name is already stored on the server and the display_name field has not been overwritten by the user).

Parameters:

app_id (str) – (required) The ID of the app.
channel (GetChannelProfileConversationChannelType) – (required) The channel. Must be one of the supported channels for this operation.
recipient_identities (List[ChannelRecipientIdentityDict]) – (required) The recipient_identities to retrieve the channel profile for.
**kwargs –
Additional parameters for the request.

Returns:

The channel profile.

Return type:

GetChannelProfileResponse

For detailed documentation, visit https://developers.sinch.com/docs/conversation/.

list_identity_conflicts(

page_size: int | None = None,

page_token: str | None = None,

**kwargs,

) → Paginator[ListIdentityConflictsResponse, ContactIdentityConflict][source]

Lists contact identity conflicts across supported SIM-based channels (SMS, MMS, RCS). Use this to identify contact records sharing the same identity (e.g., phone number), which must be resolved before enabling the Unified Contact ID feature.

Parameters:

page_size (Optional[int]) – (optional) Maximum number of conflicts to return (max 20).
page_token (Optional[str]) – (optional) Pagination token for retrieving next page.
**kwargs –
Additional parameters for the request.

Returns:

A paginator for iterating through the contact identity conflicts.

Return type:

Paginator[ListIdentityConflictsResponse, ContactIdentityConflict]

For detailed documentation, visit https://developers.sinch.com/docs/conversation/.