{"__v":14,"_id":"561764d19d753b0d00343d49","category":{"__v":0,"_id":"57f55187440418170086325a","project":"5588b8a2f6c18d0d005bba03","version":"5588b8a2f6c18d0d005bba06","sync":{"url":"","isSync":false},"reference":true,"createdAt":"2016-10-05T19:16:23.805Z","from_sync":false,"order":1,"slug":"integrations","title":"Message Integrations"},"parentDoc":null,"project":"5588b8a2f6c18d0d005bba03","user":"5588b847f6c18d0d005bba01","version":{"__v":15,"_id":"5588b8a2f6c18d0d005bba06","project":"5588b8a2f6c18d0d005bba03","createdAt":"2015-06-23T01:38:42.696Z","releaseDate":"2015-06-23T01:38:42.696Z","categories":["5588b8a3f6c18d0d005bba07","5588e9689cfea70d00371df3","5588f5921163180d00b64704","561598b121e9110d0078025a","5616f1c9d170d00d00189306","5616f5c3a410c90d00c6121e","561803dcf8c9632100ac7592","563667280441020d0000e9eb","5642570d9417b40d00c0fcd3","57bf5f02efe0050e00d50bd5","57f53fb368a53b2000e03f0f","57f55187440418170086325a","582e3afa72fd270f0006926d","5841faa973967b0f004b4a2b","58db348aa32c8419002433bb"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-10-09T06:55:13.789Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":true,"order":2,"body":"Slash commands in Mixmax can be brought up by typing a slash at the beginning of a new line when composing an email using Mixmax:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/jpHwA6ETVKaHlLlhBrjK_image02.png\",\n        \"image02.png\",\n        \"331\",\n        \"446\",\n        \"#396bbc\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nWhen the user selects a command, types space, and starts typing a search term, the menu will populate with results. These results come from the Slash Command's *Parameter Suggestions URL*. The Slash Command has full control over what to show in the list UI. Here's what the `/wiki` command shows:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/2T9ubJXOTy1LrZBMYki8_image09.png\",\n        \"image09.png\",\n        \"336\",\n        \"288\",\n        \"#3b7adf\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nThen when the user selects a result from the list, Mixmax will ask the Slash Command for content to put in the email. Here's what `/wiki` command inserts when an item in selected:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/vwhn6Kl7TG0oStTxUEHy_image05.png\",\n        \"image05.png\",\n        \"605\",\n        \"144\",\n        \"#c83a1f\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Parameters\"\n}\n[/block]\nNow let's look at the parameters that make up a Slash Command. You as the developer are responsible for building and hosting the API URLs below.\n\nTo test your integration in Mixmax, add the integration to your [Mixmax Integration Dashboard](https://app.mixmax.com/dashboard/settings/integrations).\n\n## Name\n\nString name of the command that shows up in the command menu. E.g. “Search Wikipedia”.\n\n## Command\n\nTyping this string after a slash will trigger the command. It must be globally unique. Spaces are not allowed.\n\n## Parameter placeholder\n\nString parameter placeholder text that shows up in the command menu. E.g. *\"[Search]\"*\n\n## Command Parameter Suggestions API URL\n\nURL that is called with the command text that returns an array of suggestions. If a suggestion is selected, it will be immediately sent to the resolver URL (see below). See more [information](/docs/integration-api-appendix#client-side-ajax-api-requests) about client-side requests in Mixmax.\n\nThis URL is called with the following querystring parameters:\n\n  * **user**: Email address of the Mixmax user. This is only to distinguish which account the user is logged in to (to perhaps look for an auth cookie), but should not be trusted exclusively for auth since it can be modified.\n  * **text**: The text that the user typed in after the command. So if the user types `/weather San Francisco, CA`, the text will be `San Francisco, CA`.\n  * **timezone**: The user's timezone derived using `moment.tz.guess()` in case your command needs it.\n\nThis URL is expected to return a JSON object with the following properties:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameter\",\n    \"0-0\": \"title\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"1-0\": \"text\",\n    \"0-1\": \"*String* \",\n    \"1-1\": \"*String* \",\n    \"0-2\": \"The title of the row that shows up in the result.\",\n    \"1-2\": \"The new text to replace the user’s existing text with. If omitted and the user selects this and presses enter, nothing will happen (useful for “no results found” entries).\",\n    \"2-0\": \"resolve\",\n    \"2-1\": \"*Boolean*\",\n    \"2-2\": \"If `true`, selecting this entry in the UI will automatically \\\"resolve\\\" the URL (i.e. replace the typed-in text with the result from the resolver URL below). If `false`, it simply replaces the text that the user is typing with the value of `text`. Defaults to `true`. See [example usage](https://github.com/simonxca/mixmax-soundcloud-slash-command).\"\n  },\n  \"cols\": 3,\n  \"rows\": 3\n}\n[/block]\nThis API should always return at least one result, even if it's just a \"no results found\" stub.\n\n## Command Parameter Resolver API URL\n\nThe URL called when the user presses <enter> after typing a command (unless `resolve=false` is returned), or if they selected an entry from the list of suggestions. See more [information](/docs/integration-api-appendix#client-side-ajax-api-requests) about client-side requests in Mixmax.\n\nThis URL is called with the following querystring parameters:\n\n  * **user**: Email address of the Mixmax user. See above note about not trusting this for auth.\n  * **text**: The text that the user typed in after the command. So if the user types “/weather San Francisco, CA”, the text will be “San Francisco, CA”.\n  * **timezone**: The user's timezone derived using `moment.tz.guess()`, if you need it.\n\nThis URL is expected to return a JSON object with the following properties:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"body\",\n    \"0-1\": \"*String* \",\n    \"0-2\": \"The HTML representation that is inserted into the message as a \\\"card\\\" (an immutable island of content in the editor). This can optionally have [variables](/docs/integration-api-appendix#variables-in-emails)\",\n    \"1-0\": \"subject\",\n    \"1-1\": \"*String* \",\n    \"1-2\": \"Optional (defaults to empty string). If this happens to be used inside an email message (as opposed to a Mixmax template or a Mixmax signature) that doesn’t already have a subject set, this will set the subject. For example, if the user is typing “/weather SF, CA” and presses enter, the command could automatically set the subject to “Live weather for SF, CA”\",\n    \"2-0\": \"raw\",\n    \"2-1\": \"*Boolean* \",\n    \"2-2\": \"Optional (defaults to false). True if the content should be inserted into the editor as raw HTML (i.e. not an immutable \\\"card\\\"). The user will be able to edit the content.\",\n    \"3-0\": \"enhancementId\",\n    \"3-1\": \"*String*\",\n    \"3-2\": \"Optional (advanced). If this app is a companion to an [Enhancement](http://sdk.mixmax.com/docs/overview-enhancement), it can insert content that is editable by that app's editor or use that enhancement's *activateUrl*. Let's say you're creating a weather enhancement (with id \\\"weather\\\") and a companion slash command (e.g. `/weather 94123`). You can use enhancementId and enhancementParams to insert content that has an edit icon that will bring up the weather enhancement's editor.\",\n    \"4-0\": \"enhancementParams\",\n    \"4-1\": \"*Object*\",\n    \"4-2\": \"Required only if enhancementId passed. Contains the app parameters that can be read by the app's editor.\"\n  },\n  \"cols\": 3,\n  \"rows\": 5\n}\n[/block]\nIf the command resolver URL is unable to return content because of invalid user input, it should return an HTTP status code of `400` with the json payload of `{message: '<failure reason>'}`. This will show a custom error message in the compose window. If this is not provided, then `Could not complete command` will be displayed as the default error message.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Tutorial: Building /mygiphy\"\n}\n[/block]\n*Also see our [blog post](https://mixmax.com/blog/giphy-slash-command). For a more complex example using multi-word search, see this [Soundcloud command](https://github.com/simonxca/mixmax-soundcloud-slash-command).*\n\nWe'll walk you through how to build your first Slash Command app, starting from open source Giphy for Mixmax.\n\n1. Git clone [https://github.com/mixmaxhq/giphy-example-slash-command](https://github.com/mixmaxhq/giphy-example-slash-command)\n2. Run `npm install` and `npm start`\n3. Restart Chrome in a special temporary mode so the self-signed HTTPS urls can be loaded. See [here](http://developer.mixmax.com/docs/integration-api-appendix#local-development-error-neterr_insecure_response).\n4. Verify it works by visiting https://localhost:9145/typeahead?text=winning and https://localhost:9145/resolver?text=winning in your browser. Both should return results.\n5. Open up the [Mixmax Dashboard](https://app.mixmax.com/dashboard/settings/integrations) and click *Add Slash Command*.\n6. Enter the following inputs:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Input name\",\n    \"h-1\": \"Value\",\n    \"0-0\": \"Name\",\n    \"1-0\": \"Command\",\n    \"2-0\": \"Parameter placeholder\",\n    \"3-0\": \"Typeahead API URL\",\n    \"4-0\": \"Resolver API URL\",\n    \"4-1\": \"https://localhost:9145/resolver\",\n    \"3-1\": \"https://localhost:9145/typeahead\",\n    \"2-1\": \"[Search]\",\n    \"1-1\": \"mygiphy\",\n    \"0-1\": \"My Giphy Search\"\n  },\n  \"cols\": 2,\n  \"rows\": 5\n}\n[/block]\n7. Refresh Gmail with Mixmax installed. Click Compose and type `/mygiphy` to use your new command.","excerpt":"","slug":"overview-slash-commands","type":"basic","title":"Slash Commands"}
Slash commands in Mixmax can be brought up by typing a slash at the beginning of a new line when composing an email using Mixmax: [block:image] { "images": [ { "image": [ "https://files.readme.io/jpHwA6ETVKaHlLlhBrjK_image02.png", "image02.png", "331", "446", "#396bbc", "" ] } ] } [/block] When the user selects a command, types space, and starts typing a search term, the menu will populate with results. These results come from the Slash Command's *Parameter Suggestions URL*. The Slash Command has full control over what to show in the list UI. Here's what the `/wiki` command shows: [block:image] { "images": [ { "image": [ "https://files.readme.io/2T9ubJXOTy1LrZBMYki8_image09.png", "image09.png", "336", "288", "#3b7adf", "" ] } ] } [/block] Then when the user selects a result from the list, Mixmax will ask the Slash Command for content to put in the email. Here's what `/wiki` command inserts when an item in selected: [block:image] { "images": [ { "image": [ "https://files.readme.io/vwhn6Kl7TG0oStTxUEHy_image05.png", "image05.png", "605", "144", "#c83a1f", "" ] } ] } [/block] [block:api-header] { "type": "basic", "title": "Parameters" } [/block] Now let's look at the parameters that make up a Slash Command. You as the developer are responsible for building and hosting the API URLs below. To test your integration in Mixmax, add the integration to your [Mixmax Integration Dashboard](https://app.mixmax.com/dashboard/settings/integrations). ## Name String name of the command that shows up in the command menu. E.g. “Search Wikipedia”. ## Command Typing this string after a slash will trigger the command. It must be globally unique. Spaces are not allowed. ## Parameter placeholder String parameter placeholder text that shows up in the command menu. E.g. *"[Search]"* ## Command Parameter Suggestions API URL URL that is called with the command text that returns an array of suggestions. If a suggestion is selected, it will be immediately sent to the resolver URL (see below). See more [information](/docs/integration-api-appendix#client-side-ajax-api-requests) about client-side requests in Mixmax. This URL is called with the following querystring parameters: * **user**: Email address of the Mixmax user. This is only to distinguish which account the user is logged in to (to perhaps look for an auth cookie), but should not be trusted exclusively for auth since it can be modified. * **text**: The text that the user typed in after the command. So if the user types `/weather San Francisco, CA`, the text will be `San Francisco, CA`. * **timezone**: The user's timezone derived using `moment.tz.guess()` in case your command needs it. This URL is expected to return a JSON object with the following properties: [block:parameters] { "data": { "h-0": "Parameter", "0-0": "title", "h-1": "Type", "h-2": "Description", "1-0": "text", "0-1": "*String* ", "1-1": "*String* ", "0-2": "The title of the row that shows up in the result.", "1-2": "The new text to replace the user’s existing text with. If omitted and the user selects this and presses enter, nothing will happen (useful for “no results found” entries).", "2-0": "resolve", "2-1": "*Boolean*", "2-2": "If `true`, selecting this entry in the UI will automatically \"resolve\" the URL (i.e. replace the typed-in text with the result from the resolver URL below). If `false`, it simply replaces the text that the user is typing with the value of `text`. Defaults to `true`. See [example usage](https://github.com/simonxca/mixmax-soundcloud-slash-command)." }, "cols": 3, "rows": 3 } [/block] This API should always return at least one result, even if it's just a "no results found" stub. ## Command Parameter Resolver API URL The URL called when the user presses <enter> after typing a command (unless `resolve=false` is returned), or if they selected an entry from the list of suggestions. See more [information](/docs/integration-api-appendix#client-side-ajax-api-requests) about client-side requests in Mixmax. This URL is called with the following querystring parameters: * **user**: Email address of the Mixmax user. See above note about not trusting this for auth. * **text**: The text that the user typed in after the command. So if the user types “/weather San Francisco, CA”, the text will be “San Francisco, CA”. * **timezone**: The user's timezone derived using `moment.tz.guess()`, if you need it. This URL is expected to return a JSON object with the following properties: [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Type", "h-2": "Description", "0-0": "body", "0-1": "*String* ", "0-2": "The HTML representation that is inserted into the message as a \"card\" (an immutable island of content in the editor). This can optionally have [variables](/docs/integration-api-appendix#variables-in-emails)", "1-0": "subject", "1-1": "*String* ", "1-2": "Optional (defaults to empty string). If this happens to be used inside an email message (as opposed to a Mixmax template or a Mixmax signature) that doesn’t already have a subject set, this will set the subject. For example, if the user is typing “/weather SF, CA” and presses enter, the command could automatically set the subject to “Live weather for SF, CA”", "2-0": "raw", "2-1": "*Boolean* ", "2-2": "Optional (defaults to false). True if the content should be inserted into the editor as raw HTML (i.e. not an immutable \"card\"). The user will be able to edit the content.", "3-0": "enhancementId", "3-1": "*String*", "3-2": "Optional (advanced). If this app is a companion to an [Enhancement](http://sdk.mixmax.com/docs/overview-enhancement), it can insert content that is editable by that app's editor or use that enhancement's *activateUrl*. Let's say you're creating a weather enhancement (with id \"weather\") and a companion slash command (e.g. `/weather 94123`). You can use enhancementId and enhancementParams to insert content that has an edit icon that will bring up the weather enhancement's editor.", "4-0": "enhancementParams", "4-1": "*Object*", "4-2": "Required only if enhancementId passed. Contains the app parameters that can be read by the app's editor." }, "cols": 3, "rows": 5 } [/block] If the command resolver URL is unable to return content because of invalid user input, it should return an HTTP status code of `400` with the json payload of `{message: '<failure reason>'}`. This will show a custom error message in the compose window. If this is not provided, then `Could not complete command` will be displayed as the default error message. [block:api-header] { "type": "basic", "title": "Tutorial: Building /mygiphy" } [/block] *Also see our [blog post](https://mixmax.com/blog/giphy-slash-command). For a more complex example using multi-word search, see this [Soundcloud command](https://github.com/simonxca/mixmax-soundcloud-slash-command).* We'll walk you through how to build your first Slash Command app, starting from open source Giphy for Mixmax. 1. Git clone [https://github.com/mixmaxhq/giphy-example-slash-command](https://github.com/mixmaxhq/giphy-example-slash-command) 2. Run `npm install` and `npm start` 3. Restart Chrome in a special temporary mode so the self-signed HTTPS urls can be loaded. See [here](http://developer.mixmax.com/docs/integration-api-appendix#local-development-error-neterr_insecure_response). 4. Verify it works by visiting https://localhost:9145/typeahead?text=winning and https://localhost:9145/resolver?text=winning in your browser. Both should return results. 5. Open up the [Mixmax Dashboard](https://app.mixmax.com/dashboard/settings/integrations) and click *Add Slash Command*. 6. Enter the following inputs: [block:parameters] { "data": { "h-0": "Input name", "h-1": "Value", "0-0": "Name", "1-0": "Command", "2-0": "Parameter placeholder", "3-0": "Typeahead API URL", "4-0": "Resolver API URL", "4-1": "https://localhost:9145/resolver", "3-1": "https://localhost:9145/typeahead", "2-1": "[Search]", "1-1": "mygiphy", "0-1": "My Giphy Search" }, "cols": 2, "rows": 5 } [/block] 7. Refresh Gmail with Mixmax installed. Click Compose and type `/mygiphy` to use your new command.