How to fetch original source of thread that arrives via webhook

[helgatheviking]

• PHP version: 7.4
• SDK version: 2

I have a webhook set up for new conversations. I have to parse the incoming email and then update the conversation accordingly.

Not sure how I overlooked this before but Helpscout help advised me today that they add a prefix to all html IDs

The conversation object as passed in the webhook reflects parsing that we do in-app—it's not the raw source of the email as received in your external mailbox. One of the things that that includes is appending the ex- prefix to objects brought in from outside of Help Scout.

So for example <div id="something"> becomes <div id="ex-something"> and that is messing up my domDocument parsing.

I was also told you can get the original source html via an API endpoint: https://developer.helpscout.com/mailbox-api/endpoints/conversations/threads/thread-source-rfc822/

But I would like to know if it's possible to get that somehow using the API wrapper.

Once the webhook comes in, I can get the conversation from it

$conversation    = $webhook->getConversation();
$conversation_id = $conversation->getId();

But pretty sure this doesn't include the threads... which is why I was getting the threads from the embedded property of the webhook's json payload.

Not quite sure where to go from here, so would appreciate any help!

[bkuhl]

Hey Kathy,

Unfortunately this isn't possible using the SDK today. However, I had some capacity today and I've gone ahead and opened 2 PRs, 1 targeting v2 and the other targeting v3. Once we get these merged you can update your SDK and pulling the original source will only require the conversationId and threadId. I believe the webhook itself comes with some recent threads embedded, so you should be able to get the threadId there.

[helgatheviking]

Hi Ben... that looks great. Thanks! In the meantime, I've changed my parsing to account for the new ex- prefix HS is adding to all HTML id attributes.

[bkuhl]

@helgatheviking If you update to v3.1.0 or v2.6.0 you can fetch the original source:

$source = $client->threads()->getSource($conversationId, $threadId);
print_r($source->getOriginal());

[helgatheviking]

@bkuhl Awesome! Great work. Is there any doc describing the difference between 3.0 and 2.x?

[bkuhl]

Yep! The 3.0 release notes

[helgatheviking]

@bkuhl New question related to getOriginal()... the webhook gets fired even when you create a conversation manually, or when you forward another conversation. But there's no original source for those kinds of threads.

Looking at the example

$source = $client->threads()->getSource(1189656771, 3394140565);
print_r($source->getOriginal());

what can I check for to verify that $source will have an original source to avoid errors when trying to getOriginal()? Support has mentioned that there's a source type in the webhook somewhere, but I'm not sure how to retrieve that.

[bkuhl]

Hey Kathy,

There are 2 "source" concepts for a thread in our system, and thinking about this now, getSource() may not have been the best method name choice. It sounds like support was referring to the Source shown on https://developer.helpscout.com/mailbox-api/endpoints/conversations/threads/list/ which tells you information about where the thread came from. For example:

  "source" : {
    "type" : "email",
    "via" : "customer"
  },

In this case, getSource() refers to the thread's original source in regards to the actual email we received. The best way to do this is watch for a 404 response when fetching the source. Here's an example of how to accomplish this:

try {
    $source = $client->threads()->getSource($convoId, $threadId);
} catch (\GuzzleHttp\Exception\ClientException $e) {
    if ($e->getResponse()->getStatusCode() === 404) {
        // thread's source not available
    }
}

I'll submit a PR to clarity this in the example. Hope this helps!

[helgatheviking]

Thanks Ben! As always, super helpful! And it gives me an idea on how to catch a 409 "customer exists" error... which is breaking the processing of my webhook.