{"__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":"Integration API"},"parentDoc":null,"project":"5588b8a2f6c18d0d005bba03","user":"5588b847f6c18d0d005bba01","version":{"__v":14,"_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"],"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":false,"order":2,"body":"Slash commands in Mixmax can be brought up by typing a slash at the beginning of a new line when compose an email:\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 *type ahead api 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\nWhen testing your integration, set these parameters on your [Mixmax 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/variables-in-templates#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  },\n  \"cols\": 3,\n  \"rows\": 2\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, or if they selected an entry from the list of suggestions. See more [information](/docs/variables-in-templates#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/variables-in-templates).\",\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]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Tutorial: Building /mygiphy\"\n}\n[/block]\n(note: also see our [blog post](https://mixmax.com/blog/giphy-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. Verify it works by visiting http://localhost:9145/typeahead?text=winning and http://localhost:9145/resolver?text=winning in your browser. It should not throw an error.\n4. Open up the [Mixmax Dashboard](https://app.mixmax.com/dashboard/settings/integrations) and click *Add Slash Command*.\n5. 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\": \"http://localhost:9145/resolver\",\n    \"3-1\": \"http://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]\n6. Refresh Gmail with Mixmax installed. Click Compose and type `/mygiphy` to use your new command. Note that you might need to restart Chrome in \"insecure\" mode for local testing - see instructions [here](/docs/variables-in-templates#insecure-content-https-request-blocked-when-develo).","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 compose an email: [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 *type ahead api 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. When testing your integration, set these parameters on your [Mixmax 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/variables-in-templates#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)." }, "cols": 3, "rows": 2 } [/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, or if they selected an entry from the list of suggestions. See more [information](/docs/variables-in-templates#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/variables-in-templates).", "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] [block:api-header] { "type": "basic", "title": "Tutorial: Building /mygiphy" } [/block] (note: also see our [blog post](https://mixmax.com/blog/giphy-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. Verify it works by visiting http://localhost:9145/typeahead?text=winning and http://localhost:9145/resolver?text=winning in your browser. It should not throw an error. 4. Open up the [Mixmax Dashboard](https://app.mixmax.com/dashboard/settings/integrations) and click *Add Slash Command*. 5. 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": "http://localhost:9145/resolver", "3-1": "http://localhost:9145/typeahead", "2-1": "[Search]", "1-1": "mygiphy", "0-1": "My Giphy Search" }, "cols": 2, "rows": 5 } [/block] 6. Refresh Gmail with Mixmax installed. Click Compose and type `/mygiphy` to use your new command. Note that you might need to restart Chrome in "insecure" mode for local testing - see instructions [here](/docs/variables-in-templates#insecure-content-https-request-blocked-when-develo).