Skip to content
DashboardGet API key

Get a conversation

View .md
GET

Authorization

  • Authorizationheaderrequired

    Bearer YOUR_API_KEY. Create a key in the dashboard.

Path parameters

  • conversationIdstringrequired

Responses

200The conversation.
  • conversationobjectrequired

    An inbox thread with one contact. A conversation groups every message exchanged with that contact across channels, so a contact who writes on WhatsApp and later by email stays in one thread.

    12 properties
    • idstringrequired
    • contactIdstring

      ID of the contact this thread belongs to. Absent on group threads and on threads whose contact has not been resolved yet.

    • contactIdentifierstringrequired

      The key this thread is filed under: a phone number in E.164, a WhatsApp business-scoped user ID (BSUID), or a numeric chat ID (Telegram/Instagram/Messenger). It is not always a phone number, so do not parse it as one.

    • emailstring

      Email address of the thread, when the contact was reached by email.

    • channelsstring[]required

      Every channel this thread has carried messages on.

    • lastMessageobjectrequired

      Denormalized preview of the most recent message, so a thread list needs no extra fetch.

      5 properties
      • idstringrequired
      • textstringrequired

        Text or caption. Empty when the last message carried no text (e.g. media).

      • channelstringrequired

        A transport a message travels on.

        One ofsmssms_onewaywhatsapptelegramemailinstagrammessengervoice
      • directionstringrequired
        One ofinboundoutbound
      • atstring<date-time>required
    • messageCountintegerrequired
    • unreadCountintegerrequired

      Inbound messages not yet marked read. Reset with POST /v2/conversations/{conversationId}/read.

    • whatsappobject

      WhatsApp identity, present when the contact adopted a username.

      2 properties
      • bsuidstring

        Business-scoped user ID. Can be used as to when sending.

      • usernamestring
    • createdAtstring<date-time>required
    • updatedAtstring<date-time>required
    • fromstringnullable

      The address this thread was last handled from, on the transport of its last message. Pass the conversation's id as conversationId on POST /v2/messages to reply from it. A thread opened by an API send before /v2 recorded no sender; its from is read off its messages. ?from= on the list matches threads by the recorded sender only, which messages sent through /v2 record.

401Unauthorized.
  • codestringrequired
  • messagestringrequired
  • detailsobject

    Machine-readable context. Keys that mean the same thing everywhere: - errors: present on every 400 invalid_request for an invalid body or query parameter, [{path, message, ...}], path naming the field (["to"], ["contacts", 2, "recipient"], ["limit"]). - recommendation: one sentence saying what to do next. - dashboardUrl: the dashboard screen that fixes it. - connect: on 409 no_channel, the channels this project can connect to reach the recipient, each {type, request, note, available, dashboardUrl?}; request is the exact call (POST /v2/channels with its body, or POST /v2/numbers), or null for a channel connected from the dashboard (WhatsApp, Instagram, Messenger). available: false says why in note (one-way SMS closed until business verification is approved). - address / from: the address the error is about, under the name the request used for it.

    1 properties
    • errorsobject[]
      3 properties
      • pathobject[]required
      • messagestringrequired
      • codestring
404Conversation not found, or it belongs to another project.
  • codestringrequired
  • messagestringrequired
  • detailsobject

    Machine-readable context. Keys that mean the same thing everywhere: - errors: present on every 400 invalid_request for an invalid body or query parameter, [{path, message, ...}], path naming the field (["to"], ["contacts", 2, "recipient"], ["limit"]). - recommendation: one sentence saying what to do next. - dashboardUrl: the dashboard screen that fixes it. - connect: on 409 no_channel, the channels this project can connect to reach the recipient, each {type, request, note, available, dashboardUrl?}; request is the exact call (POST /v2/channels with its body, or POST /v2/numbers), or null for a channel connected from the dashboard (WhatsApp, Instagram, Messenger). available: false says why in note (one-way SMS closed until business verification is approved). - address / from: the address the error is about, under the name the request used for it.

    1 properties
    • errorsobject[]
      3 properties
      • pathobject[]required
      • messagestringrequired
      • codestring