Shopify Ping API Reference
A list of the Shopify Ping API endpoints and their parameters.
Create a new conversation
Create a new conversation with at least one participant.
HTTP request
POST "https://{shopSubdomain}.myshopify.com/admin/api/ping-api/conversations"
Expected HTTP status response: 201 - Conversation was created.
Headers
Accept: application/json
X-Shopify-Access-Token: {access_token}
X-Shop-Domain: {shopSubdomain}.myshopify.com
JSON request body
{
"conversation": {
"topic": "new conversation topic",
"source_type": "email",
"avatar": {
"urls": [
"http://example.com/path-to-avatar"
],
"initials": "E"
},
"masks": [
{
"group": "team",
"name": "team",
"avatar": "http://example.com/path-to-group-avatar"
}
],
"participants": [
{
"id": "12345",
"shopify_user_id": 2468,
"name": "john",
"avatar": "http://example.com/path-to-john-avatar",
"group": "team",
"customer_id": 5678
}
]
}
}
Parameter | Description | Type | ||
---|---|---|---|---|
topic |
The conversation's topic. | string |
||
source_type |
The source of the conversation: email |
string |
||
avatar |
||||
urls |
An array of URL paths to the message avatars. | [string] |
||
initials |
A single character representing the conversation avatar. | string |
||
masks |
||||
group |
The type of participant. | string |
||
name |
A String that defines the group’s name. | string |
||
avatar |
The group's avatar URL. | string |
||
participants |
||||
id |
The participant's ID. | string |
||
shopify_user_id |
The participant's Shopify user ID. | integer |
||
name Required |
The participant's name. | string |
||
avatar |
The participant's avatar URL path. | string |
||
group Required |
The participant's group. | string |
||
customer_id |
The customer's ID. | integer |
Update a conversation
Update a conversation with at least one participant.
HTTP request
PUT "https://{shopSubdomain}.myshopify.com/admin/api/ping-api/conversations/{conversation_id}"
Expected HTTP status response: 200 - OK.
Headers
Accept: application/json
X-Shopify-Access-Token: {access_token}
X-Shop-Domain: {shopSubdomain}.myshopify.com
JSON request body
{
"conversation": {
"topic": "an updated topic"
}
}
Parameter | Description | Type | ||
---|---|---|---|---|
topic |
The conversation's topic. | string |
Add a participant to a conversation
Add a participant to a conversation.
HTTP request
POST "https://{shopSubdomain}.myshopify.com/admin/api/ping-api/conversations/{conversation_id}/participants"
Expected HTTP status response: 201 - Participant was added to the conversation.
Headers
Accept: application/json
X-Shopify-Access-Token: {access_token}
X-Shop-Domain: {shopSubdomain}.myshopify.com
JSON request body
{
"participant": {
"id": "12345",
"name": "janice",
"avatar": "http://example.com/path-to-avatar",
"group": "customer",
"customer_id": 5678
}
}
Parameter | Description | Type | ||
---|---|---|---|---|
id |
The participant's ID. | string |
||
shopify_user_id |
The participant's Shopify user ID. | integer |
||
name Required |
The participant's name. | string |
||
avatar |
The participant's avatar URL path. | string |
||
group Required |
The participant's group. | string |
||
customer_id |
The customer's ID. | integer |
Create a new message on a conversation
Create a new message on an existing conversation.
HTTP request
POST "https://{shopSubdomain}.myshopify.com/admin/api/ping-api/conversations/{conversation_id}/messages"
Expected HTTP status response: 201 - Message was created.
Headers
Accept: application/json
X-Shopify-Access-Token: {access_token}
X-Shop-Domain: {shopSubdomain}.myshopify.com
JSON request body
{
"message": {
"sender_id": "12345",
"shopify_user_id": 2468,
"dedupe_key": "1a2b3c4d",
"automated": false,
"content": {
"text": "new message content"
}
}
}
Parameter | Description | Type | ||
---|---|---|---|---|
sender_id |
The message sender ID. | string |
||
shopify_user_id |
The Shopify user ID of the message sender. | integer |
||
dedupe_key |
A unique nonce identifier. Messages sent with an existing dedupe key are ignored. | string |
||
automated |
Whether the message is automated or not. Automated messages do not trigger push notifications on the Ping app. | boolean |
||
content |
||||
text Required |
The new message content. | string |
Notify merchant when a conversation is seen
Send a notification to the merchant when a buyer has seen a conversation.
HTTP request
PUT "https://{shopSubdomain}.myshopify.com/admin/api/ping-api/conversations/:conversation_id/seen"
Expected HTTP status response: 200 - OK.
Headers
Accept: application/json
X-Shopify-Access-Token: {access_token}
X-Shop-Domain: {shopSubdomain}.myshopify.com
JSON request body
{
"participant_id": "12345",
"seen_timestamp": "2019-06-16T17:35:58.056Z"
}
Parameter | Description | Type | ||
---|---|---|---|---|
participant_id |
The participant's ID. | string |
||
seen_timestamp |
The date and time when the conversation was seen. | string |
Send delivery confirmation details for a message
Send delivery confirmation details for a given message.
HTTP request
POST "https://{shopSubdomain}.myshopify.com/admin/api/ping-api/conversations/{conversation_id}/messages/{message_id}/delivery_confirmation"
Expected HTTP status response: 202 - Confirmation was accepted.
Headers
Accept: application/json
X-Shopify-Access-Token: {access_token}
X-Shop-Domain: {shopSubdomain}.myshopify.com
JSON request body
{
"conversation_id": "12345",
"id": "2468",
"delivery_confirmation_details": {
"delivered": true,
"delivery_timestamp": "2019-06-16T17:35:58.056Z",
"details": "error sending confirmation details"
}
}
Parameter | Description | Type | ||
---|---|---|---|---|
conversation_id |
The ID of the conversation that contains the message. | string |
||
id |
The message ID. | string |
||
delivery_confirmation_details |
||||
delivered |
Whether the message was delivered. | boolean |
||
delivery_timestamp |
The date and time when the message was delivered. | string |
||
details |
A string describing an error in the event that the message couldn't be delivered. | string |
Remove a participant from a conversation
Remove a participant from a conversation.
HTTP request
DELETE "https://{shopSubdomain}.myshopify.com/admin/api/ping-api/conversations/{conversation_id}/participants/{participant_id}"
Expected HTTP status response: 204 - Participant was removed from the conversation.
Headers
Accept: application/json
X-Shopify-Access-Token: {access_token}
X-Shop-Domain: {shopSubdomain}.myshopify.com
Create an automated message
Create a "greeting" or "away "automated message. The automated greeting message is sent to a buyer when they first message a store. If a store has set business hours and a buyer sends a message to the store outside of the business hours, then the away message is sent.
HTTP request
PUT "https://{shopSubdomain}.myshopify.com/admin/api/ping-api/automated_messages"
Expected HTTP status response: 200 - OK.
Headers
Accept: application/json
X-Shopify-Access-Token: {access_token}
X-Shop-Domain: {shopSubdomain}.myshopify.com
JSON request body
{
"id": "greeting",
"automated_message": {
"content": "Welcome to the conversation!",
}
}
Parameter | Description | Type | ||
---|---|---|---|---|
id |
The ID of the automated message:greeting, away . |
string |
||
automated_message |
||||
content |
The automated message's content. | boolean |
Remove an automated message
Remove a "greeting" or "away" automated message.
HTTP request
DELETE "https://{shopSubdomain}.myshopify.com/admin/api/ping-api/automated_messages"
Expected HTTP status response: 200 - OK.
Headers
Accept: application/json
X-Shopify-Access-Token: {access_token}
X-Shop-Domain: {shopSubdomain}.myshopify.com
JSON request body
{
"id": "greeting"
}
Parameter | Description | Type | ||
---|---|---|---|---|
id |
The ID of the automated message: greeting, away . |
string |
Fetch shop availability
Fetches a shop's business hours and timezone.
HTTP request
GET "https://{shopSubdomain}.myshopify.com/admin/api/ping-api/availability"
Expected HTTP status response: 200 - OK.
Headers
Accept: application/json
X-Shopify-Access-Token: {access_token}
X-Shop-Domain: {shopSubdomain}.myshopify.com
Response
If a shop's availability is set to always available:
{
"availability":{
"type": "always",
"availability_rules": {
"counts": {
"total": 0,
},
"data": []
},
"time_zone": "Pacific Time (US & Canada)"
}
}
If a shop's availability specifies days:
{
"availability":{
"type": "days",
"availability_rules": {
"counts": {
"total": 5,
},
"data": [
{
"day": "monday",
"hours": [
{
"from": "2000-01-01T09:00:00.000000Z",
"to": "2000-01-01T17:00:00.000000Z"
}
]
},
{
"day": "tuesday",
"hours": [
{
"from": "2000-01-01T09:00:00.000000Z",
"to": "2000-01-01T17:00:00.000000Z"
}
]
},
{
"day": "wednesday",
"hours": [
{
"from": "2000-01-01T09:00:00.000000Z",
"to": "2000-01-01T17:00:00.000000Z"
}
]
},
{
"day": "thursday",
"hours": [
{
"from": "2000-01-01T09:00:00.000000Z",
"to": "2000-01-01T17:00:00.000000Z"
}
]
},
{
"day": "friday",
"hours": [
{
"from": "2000-01-01T09:00:00.000000Z",
"to": "2000-01-01T17:00:00.000000Z"
}
]
}
]
},
"time_zone": "Pacific Time (US & Canada)"
}
}