Messaging

The messaging API allows brands to communicate directly with creators.

The messaging feature is behind a separate allowlist. You can request access through your Snap point of contact.

Get Conversation Id

Before sending a message, the brand must create a conversation with the creator. This endpoint gets or creates a conversation between a brand and creator profile.

HTTP Request

GET

https://businessapi.snapchat.com/v1/public_profiles/{profile_id}/group_conversation

Parameters

Field name	Required	Description	Possible values
profile_id	R	Brand profile id.	UUID
creator_profile_id	R	Creator profile id.	UUID

HTTP Response

Name	Description	Possible values
request_id	A UUID to identify this request.	UUID
request_status	The status of the request.	SUCCESS, ERROR
conversation	The Conversation object.	See Conversation object details below.
debug_message	A debug message to help debug if there is an error.
display_message	Display message if there is an error.
error_code	Error code if there is an error.

Conversation Object

Field	Description	Possible Values
conversation_id	Unique identifier for a conversation.	UUID
token	Token for the conversation.	Formatted as “SnapProfileId/”+brand_profile_id

Example Response

{
  "request_id": "ecfe244d-0b1b-4787-9919-4ee7dd275a0a",
  "request_status": "SUCCESS",
  "conversation": {
    "conversation_id": "5b98ba5a-98f6-4543-a5da-746012f93d8a",
    "token": "SnapProfileId/27d0d705-b243-402f-abad-40250e491e12"
  }
}

Send Collaboration Message

A brand profile can send a message to a creator to invite them for collaboration.

Prerequisite: A Conversation Id is required to send a message. Call Get Conversation Id before sending a message.

HTTP Request

POST

https://businessapi.snapchat.com/v1/public_profiles/{profile_id}/group_conversation_messages

Parameters

Field Name	Required	Description	Possible Values
profile_id	R	Brand profile ID.	UUID
conversation_id	R	Conversation ID.	UUID
token	R	Token for the conversation.	Formatted as “SnapProfileId/”+brand_profile_id
group_conversation_messages	R	List of GroupConversationMessage objects (see below for details) to send. Currently only supports one input object each call.	Text only

GroupConversationMessage Object

Field	Required	Description	Possible Values
type	R	Message type.	Enum: TEXT (Only TEXT supported currently)
text_message	R	Message in text form.
message_id	O	Unique identifier for message.

HTTP Response

Name	Description	Possible Values
request_id	A UUID to identify this request.	UUID
request_status	The status of the request.	SUCCESS, ERROR
group_conversation_messages	GroupConversationMessageSubResponse object.	See GroupConversationMessageSubResponse object details.
debug_message	A debug message to help debug if there is an error.
display_message	Display message if there is an error.
error_code	Error code if there is an error.

GroupConversationMessageSubResponse

Field	Description	Possible Values
sub_request_status	The status of the sub-request.	SUCCESS, ERROR
group_conversation_message	GroupConversationMessage object that was sent (see below for details).	See GroupConversationMessage object details
sub_request_error_reason	Error message; empty if sub_request_status is not ERROR.

Example Response

{
  "request_id": "ecfe244d-0b1b-4787-9919-4ee7dd275a0a",
  "request_status": "SUCCESS",
  "group_conversation_messages": [
    {
      "sub_request_status": "SUCCESS",
      "group_conversation_message": {
        "message_id": "9d9cbc3e-3d78-4a80-85e4-a86a6abdcbf4",
        "type": "TEXT",
        "text_message": "Hello, this is Snap, and we want to collaborate with you!"
      },
      "sub_request_error_reason": ""
    }
  ]
}

Get Collaboration Message

A brand profile can get conversation messages between themselves and creators.

HTTP Request

GET

https://businessapi.snapchat.com/v1/public_profiles/{profile_id}/group_conversation_messages

Parameters

Field name	Required	Description	Possible Values
profile_id	R	Brand profile ID.	UUID
conversation_id	R	Conversation ID.	UUID
token	R	Token for the conversation.	Formatted as “SnapProfileId/”+brand_profile_id
limit	O	Number of messages per page.
cursor	O	Pagination encoded cursor for next page messages. The default is empty.

HTTP Response

Name	Description	Possible Values
request_id	A UUID to identify this request.	UUID
request_status	The status of the request.	SUCCESS, ERROR
group_conversation_messages	List of GroupConversationMessage objects (see below for details).	See GroupConversationMessage object details
debug_message	A debug message to help debug if there is an error.
display_message	Display message if there is an error.
error_code	Error code if there is an error.

Example Response

{
  "request_id": "efe61f1b-4412-4c58-afa9-fb22c8b71008",
  "request_status": "SUCCESS",
  "group_conversation_messages": [
    {
      "sub_request_status": "SUCCESS",
      "group_conversation_message": {
        "message_id": "8105113a-97cc-4c06-9604-97469deb8550",
        "text_message": "testing"
      }
    },
    {
      "sub_request_status": "SUCCESS",
      "group_conversation_message": {
        "message_id": "b6d83cc5-88b8-4fc7-a909-6faa39d6e382",
        "text_message": "testing another!"
      }
    }
  ],
  "paging": {
    "next_page_id": "NA",
    "next_link": "https://ingress-us-central1-gcp.api.snapchat.com?limit=2&cursor=NA"
  }
}

Get Unread Count of Group Conversation Message

A brand profile can get the number of unread group conversations between themselves and creators.

HTTP Request

GET

https://businessapi.snapchat.com/v1/public_profiles/{profile_id}/group_conversation_messages_count

Parameters

Field name	Required	Description	Possible Values
profile_id	R	Brand profile ID.	UUID

HTTP Response

Name	Description	Possible Values
request_id	A UUID to identify this request.	UUID
request_status	The status of the request.	SUCCESS, ERROR
count	The unread count of group conversation messages, expressed as a range.	< 10, 10+, or 99+
debug_message	A debug message to help debug if there is an error.
display_message	Display message if there is an error.
error_code	Error code if there is an error.

Example Response

{
  "request_id": "e08359fb-a0a6-44f2-be16-db88ada4150a",
  "request_status": "SUCCESS",
  "count": "< 10"
}