To help get you started with the Channels API, this walkthrough should act as a valuable sample to kick off your development. If you have any additional questions, please reach out to us at firstname.lastname@example.org!
1. Fill out the form for your sample channel. Because it's for a sample channel, your answers don't need to be too in-depth. Here are our suggestions for the sample channel.
|Company Name||Your company's name.|
|Contact Name||Your name.|
|Contact Email||Your email.|
|Name of channel||Sample Channel.|
|Webhook URL||Our mock server we've set up for you:
|Description of Channel||This is a sample channel.|
|Channel Contact Type||Choose whichever.|
|Attachment Types||Choose whichever.|
|Icon for your channel||Leave empty. It's an optional field.|
|Auth Method||API Token. For the sample, you can fake a token with any string. The token won't be verified in the sample channel.|
|OAuth fields||Leave blank|
2. Front will create a new Channel Type for you. A Channel Type is an entity that represents the configuration you sent to Front in the previous step. When users create a new Channel, they are creating an instance of your Channel Type.
3. Once you have received your Channel Type’s API key and Channel Type ID, keep them safe! You’ll need them to make requests to Front’s API.
4. In the Postman collection, input your Channel Type API Key (
secretKey) and Channel Type ID (
channelTypeId) as environment variables.
channelIdwill be added later, when we create a channel (an instance of your Channel Type).
5. In Front, add your new channel. (Settings > Inboxes > Add a team inbox)
- For the API Key, feel free to put anything as this is just a sample channel.
- In production, you will be responsible for:
- Validating the request is from Front
- Validating the API Token belongs to your system.
6. When the new channel is added, Front sends a request to the callback URL of your Channel Type, with the authentication payload shown in the Postman collection.
- In the channel settings page, get the channel instance’s ID (
cha_XYZ). Add this channel ID to your Postman environment (
- In production, you should maintain a mapping of which of your users are using which channel ID (do this by matching your system’s API token to a Front’s Channel ID) Look at the response of the mock server. Your callback server should return the same payload.
1. Use the
inbound_messages endpoint to send a message to Front. Observe that the endpoint generated depends on the channel ID.
- In the Postman collection, observe the payload. See the Pre-request script to understand how we generate the API Key.
- Note the
external_conversation_id. Front threads messages on the
external_conversation_id. Front will threadmessages with the same external conversation ID.
- Observe the response from Front. Front returns a
2. Respond to the message in Front - The request body sent to your callback server will match the example request body in the Postman collection.
- Front requires your callback server to respond with a
external_conversation_id. These IDs should reflect the message created in your system.
3. Import a message using
- Observe in Front that it is “sent” by the channel. Since we’re using the same
external_conversation_id, this message threads with the message in Step 1.
- Represents a message that was sent in your application that should be synced to Front.
- Notice the
webhook_urlis optional, but Front stringly recommends generating a unique webhook URL for each channel.
- Front threads messages by the
- The payloads returns by your callbacks server should have the same keys as the Postman collection.