Setup

Create your channel

Go to Settings > Accounts > Add account > Custom (Build your own). Choose whether the account should be shared or personal - this can be changed later, so we recommend starting with a personal account and sharing it when ready.

You should now see a configuration screen like this:

Here are details on each of these settings:

Account name

This name is used in your Accounts setting to identify the custom channel. It can be changed later on.

Message type

Custom channels support three different message types.

Here are the main differences between the three types:

Once your custom channel is created, you cannot update its message type.

Outgoing messages

The following settings apply only to the Text or HTML message types.

You can define whether Missive allows users to send new messages, reply to existing messages or edit recipients of a reply.

Aliases

When you reply to custom channel messages or create new messages, Missive lets you select one of the pre-defined aliases you've defined in this section. An alias can be composed of three keys: id, name and username. Your outgoing webhook may use these in any way. They are all optional, so feel free to uncheck those you won’t use:

• Allow defining recipient ID

• Allow defining recipient name

• Allow defining recipient username

You must also define the maximum number of recipients new messages and replies can have.

Webhooks

Go to the "Send messages" step for details on the webhook options.

Receive messages

To create incoming messages in your custom channel, you must use the Missive API. Learn how to get started and how to create messages in your channel using the POST /messages endpoint.

You must pass your channel ID when creating messages. You can find it under Account ID once your channel has been created.

Send messages

To send messages via the custom channel, you must define a webhook URL endpoint. Every time you send a message from Missive, the associated payload will be posted to this endpoint.

The request payload looks like this:

{
  "message": {
    "id": "a8ae9822-ec20-4cc7-989f-4ff4bc473cfe",
    "preview": "Hi, my name is Phil! How can I help you?",
    "type": "custom_text",
    "delivered_at": 1623269628,
    "updated_at": 1623269628,
    "created_at": 1623269608,
    "references": [],
    "body": "Hi, my name is Phil! How can I help you?",
    "from_field": {
      "id": null,
      "name": "My custom account",
      "username": "My custom account"
    },
    "to_fields": [
      {
        "id": "12345",
        "name": "Philippe Lehoux",
        "username": "@plehoux"
      }
    ],
    "external_id": null,
    "attachments": [],
    "author": {
      "id": "af577bfa-076f-4ff0-bcc0-9b2d578fc601",
      "email": "philippe@conferencebadge.com",
      "name": "Philippe Lehoux",
      "avatar_url": "https://missive.cdn.com/814942a3-ae65-4da5-b1ab-bd5266336ef4/philippe.png"
    }
  },
  "conversation": {
    "id": "15ff3085-4654-488d-a18f-aced2cc7dcc9",
    "subject": null,
    "latest_message_subject": "Message from Philippe Lehoux",
    "organization": null,
    "color": null,
    "assignees": [],
    "users": [
      {
        "id": "af577bfa-076f-4ff0-bcc0-9b2d578fc601",
        "name": "Philippe Lehoux",
        "email": "philippe@conferencebadge.com",
        "unassigned": false,
        "closed": false,
        "archived": false,
        "trashed": false,
        "junked": false,
        "assigned": false,
        "flagged": false,
        "snoozed": false
      }
    ],
    "attachments_count": 0,
    "messages_count": 2,
    "authors": [
      {
        "name": "My custom account",
        "address": null
      },
      {
        "name": "Philippe Lehoux",
        "address": null
      }
    ],
    "drafts_count": 0,
    "send_later_messages_count": 0,
    "tasks_count": 0,
    "completed_tasks_count": 0,
    "web_url": "https://mail.missiveapp.com/#inbox/conversations/15ff3085-4654-488d-a18f-aced2cc7dcc9",
    "app_url": "missive://mail.missiveapp.com/#inbox/conversations/15ff3085-4654-488d-a18f-aced2cc7dcc9",
    "assignee_names": "",
    "assignee_emails": "",
    "shared_label_names": "",
    "shared_labels": []
  }
}

Your server is responsible for processing this payload as needed, like creating / sending a message via a third-party API of your choice, etc.

Signature secret (validating webhook requests)

If a signature secret is defined in your custom channel settings, all webhook requests will include a X-Hook-Signature hash signature of the payload. With this signature, you can validate that the request is coming from Missive. To do so, you must compute the signature yourself and compare it to the one provided in the request header.

The signature starts with sha256= followed by a HMAC hexdigest. Here's sample code showing how to compute the signature in Ruby:

#
# `secret` is the "Signature secret" set in your custom channel settings.
# `request_body` is the full HTTP request body.
#
computed_signature = 'sha256=' + OpenSSL::HMAC.hexdigest(
  OpenSSL::Digest.new('sha256'), secret, request_body
)

Make sure to assess equality between the header signature and the one you've computed using a method that prevents timing attacks against regular equality operators. In Ruby, you can use secure_compare:

valid = Rack::Utils.secure_compare(x_hook_signature, computed_signature)