Web Hooks Reference (V1)

Updated on September 21, 2021

Web Hooks can be used by developers as a simple way to get a Web Service notified of real-time events occurring on a Crisp website. The Web Hooks are configured through your Crisp dashboard, in your website settings.

This reference contains a list of examples returned by each Web Hook.

Messages

Message Updated

  • Event: message:updated
  • Description: a message has been updated
{
  "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
  "event": "message:updated",

  "data": {
    "fingerprint": 163240180126629,
    "content": "This is an edited message!",
    "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
    "session_id": "session_36ba3566-9651-4790-afc8-ffedbccc317f"
  },

  "timestamp": 1632401830425
}
{
  "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
  "event": "message:updated",

  "data": {
    "fingerprint": 163413612446728,
    "content": {
      "id": "call-date",
      "text": "Pick your date!",

      "choices": [
        {
          "value": "1",
          "label": "Today, 1:00PM.",
          "selected": false
        },
        {
          "value": "2",
          "label": "Tomorrow, 3:45PM.",
          "selected": true
        }
      ]
    },

    "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
    "session_id": "session_36ba3566-9651-4790-afc8-ffedbccc317f",
    "routing_ids": []
  },

  "timestamp": 1634136128511
}

Message Send

  • Event: message:send
  • Description: a message has been sent from a visitor (received by operators)
{
  "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
  "event": "message:send",

  "data": {
    "type": "text",
    "origin": "chat",
    "content": "Hello Crisp, this is a message from a visitor!",
    "timestamp": 1632396148646,
    "fingerprint": 163239614854320,
    "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
    "session_id": "session_36ba3566-9651-4790-afc8-ffedbccc317f",
    "from": "user",

    "user": {
      "nickname": "visitor607",
      "user_id": "session_36ba3566-9651-4790-afc8-ffedbccc317f"
    },

    "stamped": true
  },

  "timestamp": 1632396148743
}

Message Received

  • Event: message:received
  • Description: a message has been sent from an operator (received by a visitor)
{
  "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
  "event": "message:received",

  "data": {
    "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
    "type": "text",
    "from": "operator",
    "origin": "chat",
    "content": "Hello! This is a message from an operator!",
    "fingerprint": 163239623329114,

    "user": {
      "nickname": "John Doe",
      "user_id": "012d1926-8753-4af6-9957-4853bb6fa294"
    },

    "mentions": [],
    "timestamp": 1632396233539,
    "stamped": true,
    "session_id": "session_36ba3566-9651-4790-afc8-ffedbccc317f"
  },

  "timestamp": 1632396233588
}

Message Acknowledge Read Send

  • Event: message:acknowledge:read:send
  • Description: a message has been marked as read (sent from a visitor, read by an operator)
{
  "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
  "event": "message:acknowledge:read:send",

  "data": {
    "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
    "origin": "chat",

    "fingerprints": [
      163239614854320
    ],

    "session_id": "session_36ba3566-9651-4790-afc8-ffedbccc317f"
  },

  "timestamp": 1632396219082
}

Message Acknowledge Read Received

  • Event: message:acknowledge:read:received
  • Description: a message has been marked as read (sent from an operator, read by visitor)
{
  "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
  "event": "message:acknowledge:read:received",

  "data": {
    "origin": "chat",

    "fingerprints": [
      163239623329114
    ],

    "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
    "session_id": "session_36ba3566-9651-4790-afc8-ffedbccc317f"
  },

  "timestamp": 1632396602165
}

Message Notify Unread Send

  • Event: message:notify:unread:send
  • Description: a message was not read in due time (sent from a visitor, unread by operators)
{
  "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
  "event": "message:notify:unread:send",

  "data": {
    "session_id": "session_36ba3566-9651-4790-afc8-ffedbccc317f",
    "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825"
  },

  "timestamp": 1632397209692
}

Message Notify Unread Received

  • Event: message:notify:unread:received
  • Description: a message was not read in due time (sent from an operator, unread by visitor)
{
  "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
  "event": "message:notify:unread:received",

  "data": {
    "session_id": "session_36ba3566-9651-4790-afc8-ffedbccc317f",
    "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825"
  },

  "timestamp": 1632396353781
}

Sessions

Session Set Email

  • Event: session:set_email
  • Description: an email has been set
{
  "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
  "event": "session:set_email",

  "data": {
    "email": "crisp@crisp.chat",
    "session_id": "session_36ba3566-9651-4790-afc8-ffedbccc317f",
    "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825"
  },

  "timestamp": 1632401890392
}

Session Set Phone

  • Event: session:set_phone
  • Description: a phone number has been set
{
  "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
  "event": "session:set_phone",

  "data": {
    "phone": "330987654321",
    "session_id": "session_36ba3566-9651-4790-afc8-ffedbccc317f",
    "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825"
  },

  "timestamp": 1632406430584
}

Session Set Address

  • Event: session:set_address
  • Description: an address has been set
{
  "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
  "event": "session:set_address",

  "data": {
    "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
    "session_id": "session_36ba3566-9651-4790-afc8-ffedbccc317f",
    "address": "Whip-Ma-Whop-Ma-Gate, York"
  },

  "timestamp": 1632412640818
}

Session Set Data

  • Event: session:set_data
  • Description: custom data have been set to the user profile
{
  "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
  "event": "session:set_data",

  "data": {
    "data": {
      "key_3": "value_3"
    },

    "session_id": "session_36ba3566-9651-4790-afc8-ffedbccc317f",
    "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825"
  },

  "timestamp": 1632406895238
}

Session Set Avatar

  • Event: session:set_avatar
  • Description: an avatar has been set
{
  "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
  "event": "session:set_avatar",

  "data": {
    "avatar": "https://pbs.twimg.com/profile_images/834424630630817795/TfyS4uXb_400x400.jpg",
    "session_id": "session_36ba3566-9651-4790-afc8-ffedbccc317f",
    "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825"
  },

  "timestamp": 1632407014749
}

Session Set Nickname

  • Event: session:set_nickname
  • Description: a nickname has been set
{
  "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
  "event": "session:set_nickname",

  "data": {
    "nickname": "John Doe",
    "session_id": "session_36ba3566-9651-4790-afc8-ffedbccc317f",
    "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825"
  },

  "timestamp": 1632401910906
}

Session Set State

  • Event: session:set_state
  • Description: session state changed (either: pending, resolved, unresolved)
{
  "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
  "event": "session:set_state",

  "data": {
    "state": "unresolved",
    "session_id": "session_36ba3566-9651-4790-afc8-ffedbccc317f",
    "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825"
  },

  "timestamp": 1632396233579
}

Session Set Block

  • Event: session:set_block
  • Description: messages from session have been blocked (or unblocked)
{
  "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
  "event": "session:set_block",

  "data": {
    "session_id": "session_36ba3566-9651-4790-afc8-ffedbccc317f",
    "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
    "is_blocked": true
  },

  "timestamp": 1632407477178
}

Session Set Segments

  • Event: session:set_segments
  • Description: a segment has been assigned to session
{
  "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
  "event": "session:set_segments",

  "data": {
    "session_id": "session_36ba3566-9651-4790-afc8-ffedbccc317f",
    "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",

    "segments": [
      "segment1"
    ]
  },

  "timestamp": 1632407122511
}

Session Sync Geolocation

  • Event: session:sync:geolocation
  • Description: the session geolocation was updated
{
  "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
  "event": "session:sync:geolocation",

  "data": {
    "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
    "session_id": "session_36ba3566-9651-4790-afc8-ffedbccc317f",

    "geolocation": {
      "country": "GB",
      "region": "ENG",
      "city": "London",

      "coordinates": {
        "latitude": 51.5074,
        "longitude": -0.1196
      }
    }
  },

  "timestamp": 1632409600386
}

Session Sync System

  • Event: session:sync:system
  • Description: the session system information were updated
{
  "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
  "event": "session:sync:system",

  "data": {
    "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
    "session_id": "session_aac42ca6-80f9-49fa-b43d-36a8be4f3744",

    "system": {
      "os": {
        "name": "macOS",
        "version": "10.15.7"
      },

      "engine": {
        "name": "Blink",
        "version": "93.0.4577.63"
      },

      "browser": {
        "name": "Chrome",
        "version": "93.0.4577.63",
        "major": "93"
      },

      "useragent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/93.0.4577.63 Safari/537.36"
    }
  },

  "timestamp": 1632405174447
}

Session Sync Network

  • Event: session:sync:network
  • Description: the session network information were updated
{
  "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
  "event": "session:sync:network",

  "data": {
    "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
    "session_id": "session_36ba3566-9651-4790-afc8-ffedbccc317f",

    "network": {
      "ip": "23.106.56.52"
    }
  },

  "timestamp": 1632409600387
}

Session Sync Timezone

  • Event: session:sync:timezone
  • Description: the session timezone was updated
{
  "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
  "event": "session:sync:timezone",

  "data": {
    "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
    "session_id": "session_aac42ca6-80f9-49fa-b43d-36a8be4f3744",

    "timezone": {
      "offset": 300
    }
  },

  "timestamp": 1632405174443
}

Session Sync Locales

  • Event: session:sync:locales
  • Description: the session spoken languages were updated
{
  "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
  "event": "session:sync:locales",

  "data": {
    "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
    "session_id": "session_36ba3566-9651-4790-afc8-ffedbccc317f",

    "locales": {
      "locales": [
        "en",
        "en-GB"
      ]
    }
  },

  "timestamp": 1632396148676
}

Session Sync Events

  • Event: session:sync:events
  • Description: events have been pushed to the session
{
  "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
  "event": "session:sync:events",

  "data": {
    "events": [
      {
        "text": "product_bought",

        "data": {
          "price": "$200",
          "name": "iPhone 6S"
        },

        "color": "red",
        "timestamp": 1632409219371
      }
    ],

    "session_id": "session_36ba3566-9651-4790-afc8-ffedbccc317f",
    "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825"
  },

  "timestamp": 1632409224403
}

Session Sync Rating

  • Event: session:sync:rating
  • Description: an user rating has been submitted in session
{
  "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
  "event": "session:sync:rating",

  "data": {
    "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
    "session_id": "session_36ba3566-9651-4790-afc8-ffedbccc317f",

    "rating": {
      "stars": 5,
      "comment": "The support was super quick and very helpful! Thanks! "
    }
  },

  "timestamp": 1632410645994
}

Session Removed

  • Event: session:removed
  • Description: session has been removed (ie. conversation was deleted)
{
  "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
  "event": "session:removed",

  "data": {
    "session_id": "session_ab097597-c3a1-4274-926c-f0dee322cecf",
    "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825"
  },

  "timestamp": 1632409808497
}

People

People Profile Created

  • Event: people:profile:created
  • Description: people profile was created
{
  "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
  "event": "people:profile:created",

  "data": {
    "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
    "people_id": "46dae0e8-02c6-41f0-98ae-590b6272d99a",
    "email": "jane@crisp.chat"
  },

  "timestamp": 1632410466975
}

People Profile Updated

  • Event: people:profile:updated
  • Description: people profile was updated
{
  "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
  "event": "people:profile:updated",

  "data": {
    "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
    "people_id": "1b603e2a-c204-481c-98ec-3241fd8e4aaf",
    "email": "crisp@crisp.chat",

    "update": {
      "updated_at": 1632410257914,

      "person": {
        "geolocation": {
          "country": "GB",
          "region": "ENG",
          "city": "London",

          "coordinates": {
            "latitude": 51.5074,
            "longitude": -0.1196
          }
        },

        "locales": [
          "en",
          "en-GB"
        ],

        "nickname": "Crisp",
        "timezone": -60,
        "phone": "330987654321",
        "avatar": "https://pbs.twimg.com/profile_images/834424630630817795/TfyS4uXb_400x400.jpg",

        "employment": {
          "domain": "crisp.chat",
          "name": "Crisp",
          "role": "Software Engineer",
          "title": "CTO"
        },

        "address": "Whip-Ma-Whop-Ma-Gate, York",
        "website": "crisp.chat",
        "gender": "male"
      }
    }
  },

  "timestamp": 1632410257925
}

People Profile Removed

  • Event: people:profile:removed
  • Description: people profile has been removed
{
  "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
  "event": "people:profile:removed",

  "data": {
    "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
    "people_id": "46dae0e8-02c6-41f0-98ae-590b6272d99a",
    "email": "jane@crisp.chat"
  },

  "timestamp": 1632410506122
}

People Sync Profile

  • Event: people:sync:profile
  • Description: people profile was synchronized (ie. full data synchronization)
{
  "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
  "event": "people:sync:profile",

  "data": {
    "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
    "session_id": "session_36ba3566-9651-4790-afc8-ffedbccc317f",
    "people_id": "1b603e2a-c204-481c-98ec-3241fd8e4aaf",

    "identity": {
      "person": {
        "geolocation": {
          "country": "GB",
          "region": "ENG",
          "city": "London",

          "coordinates": {
            "latitude": 51.5074,
            "longitude": -0.1196
          }
        },

        "locales": [
          "en",
          "en-GB"
        ],

        "nickname": "Crisp",
        "timezone": -60,
        "phone": "330987654321",
        "avatar": "https://pbs.twimg.com/profile_images/834424630630817795/TfyS4uXb_400x400.jpg",

        "employment": {
          "domain": "crisp.chat",
          "name": "Crisp",
          "role": "Software Engineer",
          "title": "CTO"
        }
      },

      "company": {
        "description": "Give your customer experience a human touch.",
        "domain": "crisp.chat",

        "geolocation": {
          "country": "FR",
          "city": "Nantes"
        },

        "legal_name": "Crisp",
        "name": "Crisp",
        "url": "https://crisp.chat/"
      }
    }
  },
  "timestamp": 1632409862950
}

People Bind Session

  • Event: people:bind:session
  • Description: people profile was bound to a session
{
  "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
  "event": "people:bind:session",

  "data": {
    "session_id": "session_36ba3566-9651-4790-afc8-ffedbccc317f",
    "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
    "people_id": "6939c10e-4245-4b37-a254-f036058281b9"
  },

  "timestamp": 1632401890388
}

Campaigns

Campaign Progress

  • Event: campaign:progress
  • Description: the campaign delivery has progressed
{
  "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
  "event": "campaign:progress",

  "data": {
    "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
    "campaign_id": "d6e9d2ca-8ee0-4b43-bbce-88fe8a0e73ce",
    "progress": 100
  },

  "timestamp": 1632478337650
}

Campaign Dispatched

  • Event: campaign:dispatched
  • Description: the campaign has been dispatched
{
  "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
  "event": "campaign:dispatched",

  "data": {
    "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
    "campaign_id": "d6e9d2ca-8ee0-4b43-bbce-88fe8a0e73ce"
  },

  "timestamp": 1632478336621
}

Campaign Running

  • Event: campaign:running
  • Description: the campaign running state has changed (either running or paused)
{
  "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
  "event": "campaign:running",

  "data": {
    "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
    "campaign_id": "d6e9d2ca-8ee0-4b43-bbce-88fe8a0e73ce",
    "running": false
  },

  "timestamp": 1632478337648
}

Others

Status Health Changed

  • Event: status:health:changed
  • Description: the Crisp Status health has changed (either: healthy, sick, dead)
{
  "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
  "event": "status:health:changed",

  "data": {
    "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
    "health": "dead",

    "nodes": [
      {
        "label": "Primary load balancers",
        "replica": "tcp://edge-3.pool.net.crisp.chat:80"
      }
    ]
  },

  "timestamp": 1506985696616
}

Email Subscribe

  • Event: email:subscribe
  • Description: an user has subscribed or unsubscribed to emails
{
  "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
  "event": "email:subscribe",

  "data": {
    "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
    "email": "crisp@crisp.chat",
    "subscribed": true
  },

  "timestamp": 1632410259544
}

Email Track View

  • Event: email:track:view
  • Description: an user has opened an email
{
  "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
  "event": "email:track:view",

  "data": {
    "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
    "type": "session",
    "identifier": "session_657c6ba7-12fa-48e9-ab3c-12c55df87dac",
    "mode": "received"
  },

  "timestamp": 1632477598572
}

Plugin Event

  • Event: plugin:event
  • Description: a plugin event has been fired (eg. used for third-party Web Hooks through the chatbot plugin)
{
  "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
  "event": "plugin:event",

  "data": {
    "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
    "plugin_id": "d2fe8f2b-6fef-46f4-9aff-2d2b55989c87",
    "urn": "urn:crisp.im:bot:0",
    "name": "chatbot-fired",

    "data": {
      "customer-role": "sales",
      "session_id": "session_36ba3566-9651-4790-afc8-ffedbccc317f"
    }
  },

  "timestamp": 1632410858300
}