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, sms, messages. 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
nameRequired The participant's name. string
avatar The participant's avatar URL path. string
groupRequired 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
nameRequired The participant's name. string
avatar The participant's avatar URL path. string
groupRequired 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
textRequired 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)"
  }
}