# Send a message

You can send a message from a Conversation app to a contact associated with that app. If the recipient is not associated with an existing contact, a new contact will be created.

The message is added to the active conversation with the contact if a conversation already exists. If no active conversation exists a new one is started automatically.

You can find all of your IDs and authentication credentials on the Sinch Customer Dashboard.

Endpoint: POST /v1/projects/{project_id}/messages:send
Version: 1.0
Security: Basic, oAuth2

## Path parameters:

  - `project_id` (string, required)
    The unique ID of the project. You can find this on the Sinch Dashboard.

## Request fields (application/json):

  - `app_id` (string, required)
    The ID of the app sending the message.
    Example: "{APP_ID}"

  - `recipient` (object, required)
    Identifies the recipient. If [Dispatch Mode](https://developers.sinch.com/docs/conversation/processing-modes/) is used, you must use the identified_by field.

  - `message` (object, required)
    A message originating from a Conversation API app

  - `message.explicit_channel_message` (object)
    Allows you to specify a channel and define a corresponding channel specific message payload that will override the standard Conversation API message types. The key in the map must point to a valid conversation channel as defined in the enum ConversationChannel. The message content must be provided in a string format. You may use the [transcoding endpoint](https://developers.sinch.com/docs/conversation/api-reference/conversation/tag/Transcoding/) to help create your message. For more information about how to construct an explicit channel message for a particular channel, see that [channel's corresponding documentation](https://developers.sinch.com/docs/conversation/channel-support/) (for example, using explicit channel messages with [the WhatsApp channel](https://developers.sinch.com/docs/conversation/channel-support/whatsapp/message-support/#explicit-channel-messages)).

  - `message.explicit_channel_omni_message` (object)
    Override the message's content for specified channels. The key in the map must point to a valid conversation channel as defined in the enum ConversationChannel. The content defined under the specified channel will be sent on that channel.

  - `message.channel_specific_message` (object)
    Channel specific messages, overriding any transcoding. The structure of this property is more well-defined than the open structure of the explicit_channel_message property, and may be easier to use.
The key in the map must point to a valid conversation channel as defined in the enum ConversationChannel.

  - `message.agent` (object)
    Represents an agent that is involved in a conversation.

  - `message.agent.display_name` (string)
    Agent's display name

  - `message.agent.type` (string)
    Agent's classification. It can be UNKNOWN_AGENT_TYPE, HUMAN or BOT.
    Enum: "UNKNOWN_AGENT_TYPE", "HUMAN", "BOT"

  - `message.agent.picture_url` (string)
    The Agent's picture url.

  - `callback_url` (string)
    Overwrites the default callback url for delivery receipts for this message.
Note that you may [define a secret_for_overridden_callback_urls at the app level](https://developers.sinch.com/docs/conversation/api-reference/conversation/tag/App/#tag/App/operation/App_UpdateApp!path=callback_settings/secret_for_overridden_callback_urls&t=request); this secret will be used to sign the contents of delivery receipts when the default callback URL is overridden by this property. The REST URL should be of the form: http://host[:port]/path

  - `channel_priority_order` (array)
    Explicitly define the channels and order in which they are tried when sending the message. All channels provided in this field must be configured in the corresponding Conversation API app, or the request will be rejected.
Which channels the API will try and their priority is defined by:
1. channel_priority_order if available.
2. recipient.identified_by.channel_identities if available.
3. When recipient is a contact_id:
    - if a conversation with the contact exists: the active channel of the conversation is tried first.
    - the existing channels for the contact are ordered by contact channel preferences if given.
    - lastly the existing channels for the contact are ordered by the app priority.
    Enum: "WHATSAPP", "RCS", "SMS", "MESSENGER", "VIBERBM", "MMS", "INSTAGRAM", "TELEGRAM", "KAKAOTALK", "KAKAOTALKCHAT", "LINE", "WECHAT", "APPLEBC"

  - `channel_properties` (object)
    Channel-specific properties.
The key in the map must point to a valid channel property key as
defined by the enum ChannelPropertyKeys.
The maximum allowed property value length is 1024 characters.

  - `message_metadata` (string)
    Metadata that should be associated with the message.
Returned in the metadata field of a [Message Delivery Receipt](https://developers.sinch.com/docs/conversation/callbacks/#message-delivery-receipt). Up to 1024 characters long.

  - `conversation_metadata` (object)
    Metadata that will be associated with the conversation in CONVERSATION mode and with the specified recipient identities in DISPATCH mode.
This metadata will be propagated on MO callbacks associated
with the respective conversation or user identity. Up to 2048 characters long.
Note that the MO callback will always use the last metadata available.
Important notes:

 - If you send a message with the conversation_metadata field populated, and then send another message without populating the conversation_metadata field, the original metadata will continue be propagated on the related MO callbacks.
 - If you send a message with the conversation_metadata field populated, and then send another message with a different value for conversation_metadata in the same conversation, the latest metadata value overwrites the existing one. So, future MO callbacks will include the new metadata.
 - The conversation_metadata only accepts json objects.
 - If you send a message in DISPATCH mode while the [retention period](https://developers.sinch.com/docs/conversation/api-reference/conversation/tag/App/#tag/App/operation/App_CreateApp!path=dispatch_retention_policy/ttl_days&t=request) of the app is set to 0 (note that this value is set to 0 by default), the conversation_metadata field will not be retained.

Currently only returned in the message_metadata field of an [Inbound Message](https://developers.sinch.com/docs/conversation/callbacks/#inbound-message) callback.

  - `queue` (string)
    Select the priority type for the message
    Enum: "NORMAL_PRIORITY", "HIGH_PRIORITY"

  - `ttl` (string)
    The timeout allotted for sending the message, expressed in seconds.
Passed to channels which support it and
emulated by the Conversation API for channels without ttl support
but with message retract/unsend functionality.
Channel failover will not be performed for messages with an expired TTL.
The format is an integer with the suffix s (for seconds).
Valid integer range is 3 to 315,576,000,000 (inclusive).
Example values include 10s (10 seconds) and 86400s (24 hours).

  - `processing_strategy` (string)
    Overrides the app's [Processing Mode](https://developers.sinch.com/docs/conversation/processing-modes/). Default value is DEFAULT.
    Enum: "DEFAULT", "DISPATCH_ONLY"

  - `correlation_id` (string)
    An arbitrary identifier that will be propagated to callbacks related to this message,
including MO messages from the recipient. The correlation_id is associated with the conversation in CONVERSATION mode and with the specified recipient identities in DISPATCH mode. The MO callbacks will always include the last correlation_id available,
(which is similar to how the conversation_metadata property functions).
Up to 128 characters long.
Important note: If you send a message in DISPATCH mode while the [retention period](https://developers.sinch.com/docs/conversation/api-reference/conversation/tag/App/#tag/App/operation/App_CreateApp!path=dispatch_retention_policy/ttl_days&t=request) of the app is set to 0 (note that this value is set to 0 by default), the correlation_id field will not be retained.

  - `conversation_metadata_update_strategy` (string)
    Update strategy for the conversation_metadata field. Only supported in CONVERSATION processing mode.
    Enum: "REPLACE", "MERGE_PATCH"

  - `message_content_type` (string)
    This field classifies the message content for use with Sinch's [consent management functionality](https://developers.sinch.com/docs/conversation/consent-management/). Note that this field is currently only used with Sinch's consent management functionality, and is not referenced elsewhere by the Conversation API.
    Enum: "CONTENT_UNKNOWN", "CONTENT_MARKETING", "CONTENT_NOTIFICATION"

## Response 200 fields (application/json):

  - `accepted_time` (string)
    Timestamp when the Conversation API accepted the message for delivery to the referenced contact.

  - `message_id` (string)
    The ID of the message.

## Response 400 fields (application/json):

  - `error` (object)

  - `error.code` (integer)

  - `error.details` (array)

  - `error.details.type_url` (string)

  - `error.details.value` (string)

  - `error.message` (string)

  - `error.status` (string)

## Response 403 fields (application/json):

  - `error` (object)

  - `error.code` (integer)

  - `error.details` (array)

  - `error.details.type_url` (string)

  - `error.details.value` (string)

  - `error.message` (string)

  - `error.status` (string)

## Response 500 fields (application/json):

  - `error` (object)

  - `error.code` (integer)

  - `error.details` (array)

  - `error.details.type_url` (string)

  - `error.details.value` (string)

  - `error.message` (string)

  - `error.status` (string)

## Response 501 fields (application/json):

  - `error` (object)

  - `error.code` (integer)

  - `error.details` (array)

  - `error.details.type_url` (string)

  - `error.details.value` (string)

  - `error.message` (string)

  - `error.status` (string)