{"_id":"56e9d94b9f2cd01700c0b5db","project":"53a47666447c0ba24d1a85cb","user":{"_id":"56981fe21547031700fca1b5","username":"","name":"Oscar Sanchez"},"__v":0,"initVersion":{"_id":"569ebe312d320817003b80b8","version":"1"},"metadata":{"title":"","description":"","image":[]},"hidden":false,"createdAt":"2016-03-16T22:08:11.271Z","fullscreen":false,"htmlmode":false,"html":"","body":"Segment makes it easy to send your data to [Watsi](https://watsi.org) (and lots of other integrations). Once you've tracked your data through their open source [libraries](https://segment.com/libraries) they'll translate and route your data to Watsi in the format they understand.\n\nThe Watsi integration gives you the ability to create a trigger which will send a Watsi gift card to your users based on your Segment events!\n\n# Getting Started\n\nFirst of all, make sure you have a [Watsi](https://watsi.org) account. Once you have an account, you must have access to this integration. To get access, please email Watsi at connect@watsi.org with your account information, and we'll turn on this feature on for you.\n\nNow we can go to the [Segment settings](https://watsi.org/donor/api) page - you need to be logged in to view it - where you will see a few tabs:\n\n+ Account Information - Here is where you can find your Api Auth Token and your email, the two necessary fields for enabling Watsi as a Segment integration (more on that below).\n+ Activity Log - Here is where you will see a list of actions that Watsi has taken because of the integration. You will be able to keep track of successful triggers and also get insights as to any failures you might receive.\n+ Segment Events - In this pane, you can create, edit, and delete your custom triggers that Watsi will attempt to send gift cards for.\n\n## Segment Events\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/Q60GI7qsSrGwsggFO15U_Screen%20Shot%202016-06-01%20at%204.58.07%20PM.png\",\n        \"Screen Shot 2016-06-01 at 4.58.07 PM.png\",\n        \"1154\",\n        \"880\",\n        \"#05b4dc\",\n        \"\"\n      ],\n      \"caption\": \"The Segment Events pane\"\n    }\n  ]\n}\n[/block]\nHere you will see a list of events you have created triggers for. In this example, I have created a trigger for a `Sign Up` event that when read by Watsi will send a Gift Card to the recipient (presumably someone who signs up for your service) for $10. Let's add a new trigger for someone upgrading their accounts.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/LOPEZfbdR7CM3KDNEPvZ_Screen%20Shot%202016-06-01%20at%205.03.18%20PM.png\",\n        \"Screen Shot 2016-06-01 at 5.03.18 PM.png\",\n        \"1142\",\n        \"1068\",\n        \"#04b4dc\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nNotice that Watsi can currently only create triggers based on Segment `track` calls. If you would like to expand on other Segment call types, let us know!\n\nFinally, once I click `Save`, our trigger will be made.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/snSUdPdoTCuSHQTt3sWA_Screen%20Shot%202016-06-01%20at%205.05.11%20PM.png\",\n        \"Screen Shot 2016-06-01 at 5.05.11 PM.png\",\n        \"1104\",\n        \"1010\",\n        \"#06b4dc\",\n        \"\"\n      ],\n      \"caption\": \"Voilá!\"\n    }\n  ]\n}\n[/block]\nThat's pretty much all there is to set up on the Watsi side of this. However, no gift cards are being sent yet! That's because we haven't turned on the Watsi Segment integration yet. Let's go to our Segment dashboard and look at the Watsi Integration:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/TGNHBs9mSdyQRXwXYlfa_Screen%20Shot%202016-06-01%20at%205.07.49%20PM.png\",\n        \"Screen Shot 2016-06-01 at 5.07.49 PM.png\",\n        \"1544\",\n        \"1228\",\n        \"#54a890\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nWe're going to want to add our API Auth Token and email that we saw earlier and click on `Enable Integration`. Now things should be good to go. Let's talk about what the events should look like.\n\n# Track\n\nWhen you call [track](https://segment.com/docs/spec/track/), Segment will send the event to Watsi with the event `name` and `properties` you provide. For Watsi's integration, we accept any track event, but we only do something for the triggers you've set above. Let's say you named the event `Sign Up`\n\n### Sign Up\n\nIf you'd like to send a [Watsi gift card](https://watsi.org/gift-cards) to one of your customers, all you have to do is send us this `track` event along with the following properties:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"property key\",\n    \"h-1\": \"description\",\n    \"0-0\": \"name\",\n    \"0-1\": \"The name of the customer who will receive a gift card.\",\n    \"1-0\": \"email\",\n    \"1-1\": \"The customer's email to send the gift card to.\",\n    \"2-0\": \"\",\n    \"2-1\": \"A positive integer of _*cents*_ (USD) which will be the value of the gift card.\\n\\n_e.g._ A $5.00 gift card would have an `amount` of `500`\"\n  },\n  \"cols\": 2,\n  \"rows\": 2\n}\n[/block]\n### Responses\n\nIf a gift card is successful, an empty HTTP `200` is returned, as [Segment docs](https://segment.com/docs/partners/direct-integration/#response-body) specify. This means your customer should receive a gift card to their email address!\n\n### Example Calls\n\nHere's an example of a `track` call with most [common fields](https://segment.com/docs/spec/common/) removed and its response (an `HTTP 200 OK`):\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"type\\\": \\\"track\\\",\\n  \\\"event\\\": \\\"Send Gift Card\\\",\\n  \\\"properties\\\": {\\n    \\\"name\\\": \\\"Shigeru Miyamoto\\\",\\n    \\\"email\\\": \\\"shigeru@nintendo.com\\\"\\n  }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"successful call\"\n    },\n    {\n      \"code\": \"{}\",\n      \"language\": \"json\",\n      \"name\": \"response - 200\"\n    }\n  ]\n}\n[/block]\nHere's an example of a `track` call which will fail because the invalid email:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"type\\\": \\\"track\\\",\\n  \\\"event\\\": \\\"Send Gift Card\\\",\\n  \\\"properties\\\": {\\n    \\\"name\\\": \\\"Shigeru Miyamoto\\\",\\n    \\\"email\\\": \\\"nintendo.com\\\"\\n  }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"unsuccessful call\"\n    },\n    {\n      \"code\": \"{\\n  errors: [{\\n    \\\"title\\\": 'Invalid Attribute',\\n    \\\"detail\\\": \\\"Email is invalid\\\",\\n    \\\"status\\\": \\\"400\\\"\\n  }]\\n}\",\n      \"language\": \"json\",\n      \"name\": \"response - 400\"\n    }\n  ]\n}\n[/block]\nAnd here's an example where attributes are missing:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"type\\\": \\\"track\\\",\\n  \\\"event\\\": \\\"Send Gift Card\\\",\\n  \\\"properties\\\": {\\n    \\\"name\\\": \\\"Shigeru Miyamoto\\\"\\n  }\\n}\",\n      \"language\": \"json\"\n    },\n    {\n      \"code\": \"{\\n  errors: [{\\n    \\\"title\\\": 'Invalid Attribute',\\n    \\\"detail\\\": \\\"No 'email' property is specified\\\",\\n    \\\"status\\\": \\\"400\\\"\\n  }]\\n}\",\n      \"language\": \"json\",\n      \"name\": \"response - 400\"\n    }\n  ]\n}\n[/block]","slug":"segment-integration","title":"Segment Integration"}

Segment Integration


Segment makes it easy to send your data to [Watsi](https://watsi.org) (and lots of other integrations). Once you've tracked your data through their open source [libraries](https://segment.com/libraries) they'll translate and route your data to Watsi in the format they understand. The Watsi integration gives you the ability to create a trigger which will send a Watsi gift card to your users based on your Segment events! # Getting Started First of all, make sure you have a [Watsi](https://watsi.org) account. Once you have an account, you must have access to this integration. To get access, please email Watsi at connect@watsi.org with your account information, and we'll turn on this feature on for you. Now we can go to the [Segment settings](https://watsi.org/donor/api) page - you need to be logged in to view it - where you will see a few tabs: + Account Information - Here is where you can find your Api Auth Token and your email, the two necessary fields for enabling Watsi as a Segment integration (more on that below). + Activity Log - Here is where you will see a list of actions that Watsi has taken because of the integration. You will be able to keep track of successful triggers and also get insights as to any failures you might receive. + Segment Events - In this pane, you can create, edit, and delete your custom triggers that Watsi will attempt to send gift cards for. ## Segment Events [block:image] { "images": [ { "image": [ "https://files.readme.io/Q60GI7qsSrGwsggFO15U_Screen%20Shot%202016-06-01%20at%204.58.07%20PM.png", "Screen Shot 2016-06-01 at 4.58.07 PM.png", "1154", "880", "#05b4dc", "" ], "caption": "The Segment Events pane" } ] } [/block] Here you will see a list of events you have created triggers for. In this example, I have created a trigger for a `Sign Up` event that when read by Watsi will send a Gift Card to the recipient (presumably someone who signs up for your service) for $10. Let's add a new trigger for someone upgrading their accounts. [block:image] { "images": [ { "image": [ "https://files.readme.io/LOPEZfbdR7CM3KDNEPvZ_Screen%20Shot%202016-06-01%20at%205.03.18%20PM.png", "Screen Shot 2016-06-01 at 5.03.18 PM.png", "1142", "1068", "#04b4dc", "" ] } ] } [/block] Notice that Watsi can currently only create triggers based on Segment `track` calls. If you would like to expand on other Segment call types, let us know! Finally, once I click `Save`, our trigger will be made. [block:image] { "images": [ { "image": [ "https://files.readme.io/snSUdPdoTCuSHQTt3sWA_Screen%20Shot%202016-06-01%20at%205.05.11%20PM.png", "Screen Shot 2016-06-01 at 5.05.11 PM.png", "1104", "1010", "#06b4dc", "" ], "caption": "Voilá!" } ] } [/block] That's pretty much all there is to set up on the Watsi side of this. However, no gift cards are being sent yet! That's because we haven't turned on the Watsi Segment integration yet. Let's go to our Segment dashboard and look at the Watsi Integration: [block:image] { "images": [ { "image": [ "https://files.readme.io/TGNHBs9mSdyQRXwXYlfa_Screen%20Shot%202016-06-01%20at%205.07.49%20PM.png", "Screen Shot 2016-06-01 at 5.07.49 PM.png", "1544", "1228", "#54a890", "" ] } ] } [/block] We're going to want to add our API Auth Token and email that we saw earlier and click on `Enable Integration`. Now things should be good to go. Let's talk about what the events should look like. # Track When you call [track](https://segment.com/docs/spec/track/), Segment will send the event to Watsi with the event `name` and `properties` you provide. For Watsi's integration, we accept any track event, but we only do something for the triggers you've set above. Let's say you named the event `Sign Up` ### Sign Up If you'd like to send a [Watsi gift card](https://watsi.org/gift-cards) to one of your customers, all you have to do is send us this `track` event along with the following properties: [block:parameters] { "data": { "h-0": "property key", "h-1": "description", "0-0": "name", "0-1": "The name of the customer who will receive a gift card.", "1-0": "email", "1-1": "The customer's email to send the gift card to.", "2-0": "", "2-1": "A positive integer of _*cents*_ (USD) which will be the value of the gift card.\n\n_e.g._ A $5.00 gift card would have an `amount` of `500`" }, "cols": 2, "rows": 2 } [/block] ### Responses If a gift card is successful, an empty HTTP `200` is returned, as [Segment docs](https://segment.com/docs/partners/direct-integration/#response-body) specify. This means your customer should receive a gift card to their email address! ### Example Calls Here's an example of a `track` call with most [common fields](https://segment.com/docs/spec/common/) removed and its response (an `HTTP 200 OK`): [block:code] { "codes": [ { "code": "{\n \"type\": \"track\",\n \"event\": \"Send Gift Card\",\n \"properties\": {\n \"name\": \"Shigeru Miyamoto\",\n \"email\": \"shigeru@nintendo.com\"\n }\n}", "language": "json", "name": "successful call" }, { "code": "{}", "language": "json", "name": "response - 200" } ] } [/block] Here's an example of a `track` call which will fail because the invalid email: [block:code] { "codes": [ { "code": "{\n \"type\": \"track\",\n \"event\": \"Send Gift Card\",\n \"properties\": {\n \"name\": \"Shigeru Miyamoto\",\n \"email\": \"nintendo.com\"\n }\n}", "language": "json", "name": "unsuccessful call" }, { "code": "{\n errors: [{\n \"title\": 'Invalid Attribute',\n \"detail\": \"Email is invalid\",\n \"status\": \"400\"\n }]\n}", "language": "json", "name": "response - 400" } ] } [/block] And here's an example where attributes are missing: [block:code] { "codes": [ { "code": "{\n \"type\": \"track\",\n \"event\": \"Send Gift Card\",\n \"properties\": {\n \"name\": \"Shigeru Miyamoto\"\n }\n}", "language": "json" }, { "code": "{\n errors: [{\n \"title\": 'Invalid Attribute',\n \"detail\": \"No 'email' property is specified\",\n \"status\": \"400\"\n }]\n}", "language": "json", "name": "response - 400" } ] } [/block]