Events

Endpoint for sending events.

Send an event

Sends an event to the referenced contact from the referenced app. Note that this operation enqueues the event in a queue so a successful response only indicates that the event has been queued.

SecurityBasic or oAuth2
Request
path Parameters
project_id
required
string

The unique ID of the project. You can find this on the Sinch Dashboard.

Request Body schema: application/json
required

The event to be sent.

app_id
required
string

The ID of the app sending the event.

required
Contact ID (object) or Channel Identities (object) (RecipientRequest)

Identifies the recipient. If Dispatch Mode is used, you must use the identified_by field.

required
object (App Event Type)
callback_url
string

Overwrites the default callback url for delivery receipts for this message The REST URL should be of the form: http://host[:port]/path

channel_priority_order
Array of strings (Channel Identifier)

Optional. A single element array that dictates on what channel should the Conversation API try to send the event. It overrides any default set on the contact. Providing more than one option has no effect.

Items Enum: "WHATSAPP" "RCS" "SMS" "MESSENGER" "VIBER" "VIBERBM" "MMS" "INSTAGRAM" "TELEGRAM" "KAKAOTALK" "KAKAOTALKCHAT" "LINE" "WECHAT" "APPLEBC"
event_metadata
string

Optional. Eventual metadata that should be associated to the event.

queue
string (MessageQueue)
Default: "NORMAL_PRIORITY"

Select the priority type for the message

Enum: "NORMAL_PRIORITY" "HIGH_PRIORITY"
Responses
200

A successful response.

Response Schema: application/json
accepted_time
string <date-time>

Accepted timestamp.

event_id
string

Event id.

400

Malformed request. See common error responses for more information.

401

Incorrect credentials. See common error responses for more information.

403

Correct credentials but you don't have access to the requested resource. See common error responses for more information.

500

Correct credentials but you don't have access to the requested resource. See common error responses for more information.

501

Something went wrong on our end, try again with exponential back-off. See common error responses for more information.

post/v1/projects/{project_id}/events:send
Request samples
application/json
{
  • "app_id": "string",
  • "event": { },
  • "recipient": { }
}
Response samples
application/json
{
  • "accepted_time": "2019-08-24T14:15:22Z",
  • "event_id": "string"
}

Get an event

Get event from ID

SecurityBasic or oAuth2
Request
path Parameters
project_id
required
string

The unique ID of the project. You can find this on the Sinch Dashboard.

event_id
required
string

The unique ID of the event.

Responses
200

A successful response.

Response Schema: application/json
id
required
string

The ID of the event.

required
object (Channel Identity)

A unique identity of message recipient on a particular channel. For example, the channel identity on SMS, WHATSAPP or VIBERBM is a MSISDN phone number.

processing_mode
required
string (ProcessingMode)
Default: "DISPATCH"

Whether or not Conversation API should store contacts and conversations for the app. For more information, see Processing Modes.

Enum Value Description
CONVERSATION

Creates contacts and conversations automatically when a message is sent or received and there's no existing contact or active conversation.

DISPATCH

The default Processing Mode. Does not associate messages with contacts and conversations. This processing mode is mostly intended for unidirectional high volume SMS use cases. The lack of contacts and conversations limits some API features as related data won't be queryable in the Contact and Conversation APIs.

direction
string (ConversationDirection)
Default: "UNDEFINED_DIRECTION"
Enum: "UNDEFINED_DIRECTION" "TO_APP" "TO_CONTACT"
App Event Type (object) or Contact Event Type (object) or Contact Message Event Type (object)

The content of the events.

conversation_id
string

Optional. The ID of the event's conversation. Will not be present for apps in Dispatch Mode.

contact_id
string

Optional. The ID of the contact. Will not be present for apps in Dispatch Mode.

accept_time
string <date-time>
400

Malformed request. See common error responses for more information.

401

Incorrect credentials. See common error responses for more information.

403

Correct credentials but you don't have access to the requested resource. See common error responses for more information.

500

Correct credentials but you don't have access to the requested resource. See common error responses for more information.

501

Something went wrong on our end, try again with exponential back-off. See common error responses for more information.

get/v1/projects/{project_id}/events/{event_id}
Request samples 
Response samples 
application/json
{
  • "direction": "UNDEFINED_DIRECTION",
  • "event": {
    • "app_event": {
      }
    },
  • "id": "string",
  • "conversation_id": "string",
  • "contact_id": "string",
  • "channel_identity": {
    • "app_id": "string",
    • "channel": "WHATSAPP",
    • "identity": "string"
    },
  • "accept_time": "2019-08-24T14:15:22Z",
  • "processing_mode": "CONVERSATION"
}
Delete an event
Delete a specific event by its ID.


SecurityBasic or oAuth2 
Request 
path Parameters
project_id
required
string
The unique ID of the project. You can find this on the Sinch Dashboard.


 
event_id
required
string
The unique ID of the event.


 
Responses 
200
A successful response.


400
Malformed request. See common error responses for more information.


401
Incorrect credentials. See common error responses for more information.


403
Correct credentials but you don't have access to the requested resource. See common error responses for more information.


500
Correct credentials but you don't have access to the requested resource. See common error responses for more information.


501
Something went wrong on our end, try again with exponential back-off. See common error responses for more information.


delete/v1/projects/{project_id}/events/{event_id}
Request samples 
Response samples 
application/json
{
  • "code": 400,
  • "message": "Malformed request",
  • "status": "INVALID_REQUEST",
  • "details": [ ]
}
List events
List all events in a project


SecurityBasic or oAuth2 
Request 
path Parameters
project_id
required
string
The unique ID of the project. You can find this on the Sinch Dashboard.


 
query Parameters
conversation_id
string
Resource name (id) of the conversation. One of conversation_id or contact_id needs to be present.


 
contact_id
string
Resource name (id) of the contact. One of conversation_id or contact_id needs to be present.


 
page_size
integer <int32> 
Maximum number of events to fetch. Defaults to 10
and the maximum is 20.


 
page_token
string
Next page token previously returned if any. When specifying this token, make sure to use the same values
for the other parameters from the request that originated the token, otherwise the paged results may be inconsistent.


 
Responses 
200
A successful response.


Response Schema: application/json
Array of objects (Conversation Event) 
List of ConversationsEvents.


 
next_page_token
string
Token that should be included in the next request to fetch the next page.


 
400
Malformed request. See common error responses for more information.


401
Incorrect credentials. See common error responses for more information.


403
Correct credentials but you don't have access to the requested resource. See common error responses for more information.


500
Correct credentials but you don't have access to the requested resource. See common error responses for more information.


501
Something went wrong on our end, try again with exponential back-off. See common error responses for more information.


get/v1/projects/{project_id}/events
Request samples 
Response samples 
application/json
{
  • "events": [
    • {
      }
    ],
  • "next_page_token": "string"
}
SecurityPrivacyLegal & ComplianceCookie Statement
© 2025 Sinch. All rights reserved.