ContactsContract.Intents

public static final class ContactsContract.Intents
extends Object

java.lang.Object
   ↳ android.provider.ContactsContract.Intents


Contains helper classes used to create or manage Intents that involve contacts.

Summary

Nested classes

class ContactsContract.Intents.Insert

Convenience class that contains string constants used to create contact Intents

Constants

String ACTION_VOICE_SEND_MESSAGE_TO_CONTACTS

Activity Action: Initiate a message to someone by voice.

String ATTACH_IMAGE

Starts an Activity that lets the user pick a contact to attach an image to.

String CONTACTS_DATABASE_CREATED

This is the intent that is fired when the contacts database is created.

String EXTRA_CREATE_DESCRIPTION

Used with SHOW_OR_CREATE_CONTACT to specify an exact description to be shown when prompting user about creating a new contact.

String EXTRA_FORCE_CREATE

Used with SHOW_OR_CREATE_CONTACT to force creating a new contact if no matching contact found.

String EXTRA_RECIPIENT_CONTACT_CHAT_ID

This extra specifies a messaging app\u2019s unique ID(s) for the contact(s), used with ACTION_VOICE_SEND_MESSAGE_TO_CONTACTS to supply the recipient(s).

String EXTRA_RECIPIENT_CONTACT_NAME

This extra specifies the contact name (full name from the Contacts Provider), used with ACTION_VOICE_SEND_MESSAGE_TO_CONTACTS to supply the recipient.

String EXTRA_RECIPIENT_CONTACT_URI

This extra specifies a content provider uri(s) for the contact(s) (if the contacts were located in the Contacts Provider), used with ACTION_VOICE_SEND_MESSAGE_TO_CONTACTS to supply the recipient(s).

String INVITE_CONTACT

This is the intent that is fired when the user clicks the "invite to the network" button on a contact.

String METADATA_ACCOUNT_TYPE

A string associated with an ACTION_VOICE_SEND_MESSAGE_TO_CONTACTS activity describing RawContacts#ACCOUNT_TYPE for the corresponding Contacts Provider implementation.

String METADATA_MIMETYPE

A string associated with an ACTION_VOICE_SEND_MESSAGE_TO_CONTACTS activity describing DataColumns#MIMETYPE for the corresponding Contacts Provider implementation.

String SEARCH_SUGGESTION_CLICKED

This is the intent that is fired when a search suggestion is clicked on.

String SEARCH_SUGGESTION_CREATE_CONTACT_CLICKED

This is the intent that is fired when a search suggestion for creating a contact is clicked on.

String SEARCH_SUGGESTION_DIAL_NUMBER_CLICKED

This is the intent that is fired when a search suggestion for dialing a number is clicked on.

String SHOW_OR_CREATE_CONTACT

Takes as input a data URI with a mailto: or tel: scheme.

Public constructors

Intents()

Inherited methods

Constants

ACTION_VOICE_SEND_MESSAGE_TO_CONTACTS

Added in API level 24
public static final String ACTION_VOICE_SEND_MESSAGE_TO_CONTACTS

Activity Action: Initiate a message to someone by voice. The message could be text, audio, video or image(photo). This action supports messaging with a specific contact regardless of the underlying messaging protocol used.

The action could be originated from the Voice Assistant as a voice interaction. In such case, a receiving activity that supports Intent.CATEGORY_VOICE could check return value of Activity.isVoiceInteractionRoot() before proceeding. By doing this check the activity verifies that the action indeed was initiated by Voice Assistant and could send a message right away, without any further input from the user. This allows for a smooth user experience when sending a message by voice. Note: this activity must also support the Intent.CATEGORY_DEFAULT so it can be found by VoiceInteractionSession.startVoiceActivity(Intent).

When the action was not initiated by Voice Assistant or when the receiving activity does not support Intent.CATEGORY_VOICE, the activity must confirm with the user before sending the message (because in this case it is unknown which app sent the intent, it could be malicious).

To allow the Voice Assistant to help users with contacts disambiguation, the messaging app may choose to integrate with the Contacts Provider. You will need to specify a new MIME type in order to store your app\u2019s unique contact IDs and optional human readable labels in the Data table. The Voice Assistant needs to know this MIME type and ContactsContract.SyncColumns.ACCOUNT_TYPE that you are using in order to provide the smooth contact disambiguation user experience. The following convention should be met when performing such integration:

  • This activity should have a string meta-data field associated with it, METADATA_ACCOUNT_TYPE, which defines RawContacts#ACCOUNT_TYPE for your Contacts Provider implementation. The account type should be globally unique, for example you can use your app package name as the account type.
  • This activity should have a string meta-data field associated with it, METADATA_MIMETYPE, which defines DataColumns#MIMETYPE for your Contacts Provider implementation. For example, you can use "vnd.android.cursor.item/vnd.{$app_package_name}.profile" as MIME type.
  • When filling Data table row for METADATA_MIMETYPE, column DataColumns#DATA1 should store the unique contact ID as understood by the app. This value will be used in the EXTRA_RECIPIENT_CONTACT_CHAT_ID.
  • Optionally, when filling Data table row for METADATA_MIMETYPE, column ContactsContract.DataColumns.DATA3 could store a human readable label for the ID. For example it could be phone number or human readable username/user_id like "a_super_cool_user_name". This label may be shown below the Contact Name by the Voice Assistant as the user completes the voice action. If DATA3 is empty, the ID in DATA1 may be shown instead.
  • Note: Do not use DATA3 to store the Contact Name. The Voice Assistant will already get the Contact Name from the RawContact\u2019s display_name.
  • Note: Some apps may choose to use phone number as the unique contact ID in DATA1. If this applies to you and you\u2019d like phone number to be shown below the Contact Name by the Voice Assistant, then you may choose to leave DATA3 empty.
  • Note: If your app also uses DATA3 to display contact details in the Contacts App, make sure it does not include prefix text such as "Message +" or "Free Message +", etc. If you must show the prefix text in the Contacts App, please use a different DATA# column, and update your contacts.xml to point to this new column.
If the app chooses not to integrate with the Contacts Provider (in particular, when either METADATA_ACCOUNT_TYPE or METADATA_MIMETYPE field is missing), Voice Assistant will use existing phone number entries as contact ID's for such app.

Input: Intent.getType() is the MIME type of the data being sent. The intent sender will always put the concrete mime type in the intent type, like "text/plain" or "audio/wav" for example. If the MIME type is "text/plain", message to sent will be provided via Intent.EXTRA_TEXT as a styled CharSequence. Otherwise, the message content will be supplied through Intent.setClipData(ClipData) as a content provider URI(s). In the latter case, EXTRA_TEXT could still be supplied optionally; for example, for audio messages ClipData will contain URI of a recording and EXTRA_TEXT could contain the text transcription of this recording.

The message can have n recipients. The n-th recipient of the message will be provided as n-th elements of EXTRA_RECIPIENT_CONTACT_URI, EXTRA_RECIPIENT_CONTACT_CHAT_ID and EXTRA_RECIPIENT_CONTACT_NAME (as a consequence, EXTRA_RECIPIENT_CONTACT_URI, EXTRA_RECIPIENT_CONTACT_CHAT_ID and EXTRA_RECIPIENT_CONTACT_NAME should all be of length n). If neither of these 3 elements is provided (e.g. all 3 are null) for the recipient or if the information provided is ambiguous then the activity should prompt the user for the recipient to send the message to.

Output: nothing

Constant Value: "android.provider.action.VOICE_SEND_MESSAGE_TO_CONTACTS"

ATTACH_IMAGE

Added in API level 5
public static final String ATTACH_IMAGE

Starts an Activity that lets the user pick a contact to attach an image to. After picking the contact it launches the image cropper in face detection mode.

Constant Value: "com.android.contacts.action.ATTACH_IMAGE"

CONTACTS_DATABASE_CREATED

Added in API level 18
public static final String CONTACTS_DATABASE_CREATED

This is the intent that is fired when the contacts database is created.

The READ_CONTACT permission is required to receive these broadcasts.

Because this is an implicit broadcast, apps targeting Android O will no longer receive this broadcast via a manifest broadcast receiver. (Broadcast receivers registered at runtime with Context#registerReceiver(BroadcastReceiver, IntentFilter) will still receive it.) Instead, an app can use ProviderStatus#DATABASE_CREATION_TIMESTAMP to see if the contacts database has been initialized when it starts.

Constant Value: "android.provider.Contacts.DATABASE_CREATED"

EXTRA_CREATE_DESCRIPTION

Added in API level 5
public static final String EXTRA_CREATE_DESCRIPTION

Used with SHOW_OR_CREATE_CONTACT to specify an exact description to be shown when prompting user about creating a new contact.

Type: STRING

Constant Value: "com.android.contacts.action.CREATE_DESCRIPTION"

EXTRA_FORCE_CREATE

Added in API level 5
public static final String EXTRA_FORCE_CREATE

Used with SHOW_OR_CREATE_CONTACT to force creating a new contact if no matching contact found. Otherwise, default behavior is to prompt user with dialog before creating.

Type: BOOLEAN

Constant Value: "com.android.contacts.action.FORCE_CREATE"

EXTRA_RECIPIENT_CONTACT_CHAT_ID

Added in API level 24
public static final String EXTRA_RECIPIENT_CONTACT_CHAT_ID

This extra specifies a messaging app\u2019s unique ID(s) for the contact(s), used with ACTION_VOICE_SEND_MESSAGE_TO_CONTACTS to supply the recipient(s). The value of this extra is a String[]. The number of elements in the array should be equal to number of recipients (and consistent with EXTRA_RECIPIENT_CONTACT_URI and EXTRA_RECIPIENT_CONTACT_NAME). When the value of the element for the particular recipient is absent, it will be set to null.

The value of the elements comes from the DataColumns#DATA1 column in Contacts Provider with DataColumns#MIMETYPE from METADATA_MIMETYPE (if both METADATA_ACCOUNT_TYPE and METADATA_MIMETYPE are specified by the app; otherwise, the value will be a phone number), and should be the unambiguous contact endpoint. This value is app-specific, it could be some proprietary ID or a phone number.

Constant Value: "android.provider.extra.RECIPIENT_CONTACT_CHAT_ID"

EXTRA_RECIPIENT_CONTACT_NAME

Added in API level 24
public static final String EXTRA_RECIPIENT_CONTACT_NAME

This extra specifies the contact name (full name from the Contacts Provider), used with ACTION_VOICE_SEND_MESSAGE_TO_CONTACTS to supply the recipient. The value of this extra is a String[]. The number of elements in the array should be equal to number of recipients (and consistent with EXTRA_RECIPIENT_CONTACT_URI and EXTRA_RECIPIENT_CONTACT_CHAT_ID). When the value of the element for the particular recipient is absent, it will be set to null.

The value of the elements comes from RawContact's display_name column.

Example value: {"Jane Doe"}

Constant Value: "android.provider.extra.RECIPIENT_CONTACT_NAME"

EXTRA_RECIPIENT_CONTACT_URI

Added in API level 24
public static final String EXTRA_RECIPIENT_CONTACT_URI

This extra specifies a content provider uri(s) for the contact(s) (if the contacts were located in the Contacts Provider), used with ACTION_VOICE_SEND_MESSAGE_TO_CONTACTS to supply the recipient(s). The value of this extra is a String[]. The number of elements in the array should be equal to number of recipients (and consistent with EXTRA_RECIPIENT_CONTACT_CHAT_ID and EXTRA_RECIPIENT_CONTACT_NAME). When the value of the element for the particular recipient is absent, it will be set to null.

Note: one contact may have multiple accounts (e.g. Chat IDs) on a specific messaging platform, so this may be ambiguous. E.g., one contact \u201cJohn Smith\u201d could have two accounts on the same messaging app.

Example value: {"content://com.android.contacts/contacts/16"}

Constant Value: "android.provider.extra.RECIPIENT_CONTACT_URI"

INVITE_CONTACT

Added in API level 14
public static final String INVITE_CONTACT

This is the intent that is fired when the user clicks the "invite to the network" button on a contact. Only sent to an activity which is explicitly registered by a contact provider which supports the "invite to the network" feature.

Intent#getData() contains the lookup URI for the contact.

Constant Value: "com.android.contacts.action.INVITE_CONTACT"

METADATA_ACCOUNT_TYPE

Added in API level 24
public static final String METADATA_ACCOUNT_TYPE

A string associated with an ACTION_VOICE_SEND_MESSAGE_TO_CONTACTS activity describing RawContacts#ACCOUNT_TYPE for the corresponding Contacts Provider implementation.

Constant Value: "android.provider.account_type"

METADATA_MIMETYPE

Added in API level 24
public static final String METADATA_MIMETYPE

A string associated with an ACTION_VOICE_SEND_MESSAGE_TO_CONTACTS activity describing DataColumns#MIMETYPE for the corresponding Contacts Provider implementation.

Constant Value: "android.provider.mimetype"

SEARCH_SUGGESTION_CLICKED

Added in API level 5
public static final String SEARCH_SUGGESTION_CLICKED

This is the intent that is fired when a search suggestion is clicked on.

Constant Value: "android.provider.Contacts.SEARCH_SUGGESTION_CLICKED"

SEARCH_SUGGESTION_CREATE_CONTACT_CLICKED

Added in API level 5
public static final String SEARCH_SUGGESTION_CREATE_CONTACT_CLICKED

This is the intent that is fired when a search suggestion for creating a contact is clicked on.

Constant Value: "android.provider.Contacts.SEARCH_SUGGESTION_CREATE_CONTACT_CLICKED"

SEARCH_SUGGESTION_DIAL_NUMBER_CLICKED

Added in API level 5
public static final String SEARCH_SUGGESTION_DIAL_NUMBER_CLICKED

This is the intent that is fired when a search suggestion for dialing a number is clicked on.

Constant Value: "android.provider.Contacts.SEARCH_SUGGESTION_DIAL_NUMBER_CLICKED"

SHOW_OR_CREATE_CONTACT

Added in API level 5
public static final String SHOW_OR_CREATE_CONTACT

Takes as input a data URI with a mailto: or tel: scheme. If a single contact exists with the given data it will be shown. If no contact exists, a dialog will ask the user if they want to create a new contact with the provided details filled in. If multiple contacts share the data the user will be prompted to pick which contact they want to view.

For mailto: URIs, the scheme specific portion must be a raw email address, such as one built using Uri#fromParts(String, String, String).

For tel: URIs, the scheme specific portion is compared to existing numbers using the standard caller ID lookup algorithm. The number must be properly encoded, for example using Uri#fromParts(String, String, String).

Any extras from the Insert class will be passed along to the create activity if there are no contacts to show.

Passing true for the EXTRA_FORCE_CREATE extra will skip prompting the user when the contact doesn't exist.

Constant Value: "com.android.contacts.action.SHOW_OR_CREATE_CONTACT"

Public constructors

Intents

public Intents ()