1. The Authorization.Id that is coming through in the request doesn't mean anything to us at the moment. It’s not clear how this is created or where it comes from. We did see; however, that the Payload.Conversation.Assignee.Id is the same value we are already storing on our side when setting up the Integration to send messages. This looks like an easy way for us to identify who the message is for. Will this value always be populated when we're getting messages in the webhook or is it possible to get a message without an Assignee?

The authorization.id represents the ID of a Company instance (or tenant) in Front (see docs). If you’re building this integration for many Front customers to install. 

Relying on an assignee would not be appropriate here, as the assignee object will be null when conversations are not assigned. 

2. The attachment object in the payload does not contain any byte or steam data but it does have a URL. When we go to this URL we get an unauthorized response. Is there another API endpoint we should be using to access Front Attachments we receive in the Incoming Message payload?

Requests to the download attachment endpoint require authentication (same as any other REST API requests). The same API token you use to push messages into Front should work to authenticate requests to this endpoint.

3. Part of our normal email process when reading from other mailboxes is that the user can apply a post processing action. This would typically be marking the message as read/seen, archiving it, or deleting it. Can you point us to the endpoints that would allow us to perform these actions against the message in Front? We are assuming we would use the Payload.Id or the Payload.Target.Data.Id for this? 

You can use the PATCH /conversations/:conv_id endpoint to set the status to archived or deleted (trashed). Front does not support updating the read/unread status via the API. 

You would use the conversation ID (it begins cnv_...). The target field varies, and describes what is happening. For example, for an inbound message event, the target is the message. The conversation base URI can be retrieved from the target.data._links.related.conversation field. 

Hi Jason,

Thank you very much for the detailed answers. Answers 2 and 3 are extremely helpful and we should have no problem incorporating these. 

I’m still confused on question 1. I understand that the company id that comes through in the authorization request per the doc link. What I don’t understand is how we’re supposed to know who it belongs to. At what point in the process of a customer setting up the webhook do we first encounter this ID and how can we possibly link it back to a specific customer. Also, it’s company specific and not user specific? We’re expecting to tie incoming messages to users not companies. I’m trying to understand how we can capture and link this id to a specific user so that we can then link an incoming message back to them. We had planned on using a single webhook url for all users and in looking at the data the assignee was our best bet since it was an ID that we already recognized and stored for that user. If we need to use the company id instead I’d need to know how to get from a company level back to a user level and how to identify it the first time we encounter it.

So it’s important to note that OAuth connections between Front and external apps can only;

• be created by an company admin user in Front
• access shared resources (no private teammate resources)
• get scoped at the company-level; if two admin teammates in the same Front account connect Front with an external app, that app would receive the same set of permissions twice, and they would not be associated with a specific teammate.

So working with this knowledge, the cmp_… Company ID is the identifier that you use to differentiate between your customers. When you initially configure a Webhook subscription, this company ID is passed to your webhook as part of the initializing payload. 

So in summary, there’s no way to connect a received event back to the teammate who connected Front with your app. Note that you can receive events which are not associated with a teammate (such as a new inbound message in a shared inbox; it may not be assigned to a teammate, or an event (tag/archive/auto-reply/etc) being applied by a rule).

Hi Jason,

This is unfortunate but I understand and I think we can still make it work based on matching email addresses included as recipients to people in our system.

As far as the company Id goes. maybe I’m not understanding how each company will be setup. I thought they would log into Front, install or subscribe to our app and initialize this on their end in Front. If that happens the system sends us the new company ID, how are we supposed to know who it’s for? 

Is there a registration process I’m missing?

If your webhook is part of an app that you are publishing on our App Store, you must add OAuth to the app so that customers can authorize that Front events be sent to your webhook from their instance (See docs). This is the part where you can establish the connection between a Front company ID and your own records.

I hope that helps!