Webhook API

Example

POST /incoming_message.php HTTP/1.1
Host: yourserver.example.com
Content-Type: application/x-www-form-urlencoded
...

event=incoming_message&from_number=%2B16505550123&content=Hello+world...

Example

<?php
    $webhook_secret = 'YOUR_WEBHOOK_SECRET_HERE';

    if ($_POST['secret'] !== $webhook_secret)
    {
        header('HTTP/1.1 403 Forbidden');
        echo "Invalid webhook secret";
    }
    else
    {
        if ($_POST['event'] == 'incoming_message')
        {
            $content = $_POST['content'];
            $from_number = $_POST['from_number'];
            $phone_id = $_POST['phone_id'];

            // do something with the message, e.g. send an autoreply
            header("Content-Type: application/json");
            echo json_encode([
                'messages' => [
                    ['content' => "Thanks for your message!"]
                ]
            ]);
        }
    }

from django.views.decorators.csrf import csrf_exempt
from django.http import HttpResponse
import json

@csrf_exempt
def webhook(request):
    webhook_secret = 'YOUR_WEBHOOK_SECRET_HERE'

    if request.POST.get('secret') != webhook_secret:
        return HttpResponse("Invalid webhook secret", 'text/plain', 403)

    if request.POST.get('event') == 'incoming_message':
        content = request.POST.get('content')
        from_number = request.POST.get('from_number')
        phone_id = request.POST.get('phone_id')

        # do something with the message, e.g. send an autoreply

        return HttpResponse(json.dumps({
            'messages': [
                {'content': "Thanks for your message!"}
            ]
        }), 'application/json')

/*
 *  Sample code depends on the Java JSON library:
 *    http://mvnrepository.com/artifact/org.json/json/20090211
 */
import java.io.IOException;
import java.io.PrintWriter;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import org.json.JSONArray;
import org.json.JSONException;
import org.json.JSONObject;

public class WebhookStatusServlet extends HttpServlet
{
    @Override
    protected void doPost(HttpServletRequest request, HttpServletResponse response)
            throws ServletException, IOException {

        PrintWriter out = response.getWriter();

        String webhookSecret = "YOUR_WEBHOOK_SECRET_HERE";

        if (!webhookSecret.equals(request.getParameter("secret")))
        {
            response.setStatus(403);
            out.write("Invalid webhook secret");
        }
        else if ("incoming_message".equals(request.getParameter("event")))
        {
            String content = request.getParameter("content");
            String fromNumber = request.getParameter("from_number");
            String phoneId = request.getParameter("phone_id");

            // do something with the message, e.g. send an autoreply
            response.setContentType("application/json");

            try
            {
                JSONArray messages = new JSONArray();
                JSONObject reply = new JSONObject();
                reply.put("content", "Thanks for your message!");
                messages.put(reply);

                JSONObject json = new JSONObject();
                json.put("messages", messages);

                json.write(out);
            }
            catch (JSONException ex)
            {
                throw new ServletException(ex);
            }
        }
    }
}

using System;
using System.Collections.Generic;
using System.Web;
using System.Web.Mvc;

namespace MyMVCApplication.Controllers
{
    public class HomeController : Controller
    {
        public ActionResult Index()
        {
            String statusSecret = "YOUR_STATUS_SECRET_HERE";

            if (Request["secret"] != statusSecret)
            {
                Response.StatusCode = 403;
                return Content("Invalid status secret");
            }

            if (Request["event"] == "incoming_message")
            {
                String content = Request["content"];
                String fromNumber = Request["from_number"];
                String phoneId = Request["phone_id"];

                // do something with the message, e.g. send an autoreply
                Dictionary<string,object> reply = new Dictionary<string,object>();
                reply["content"] = "Thanks for your message!";

                Dictionary<string,object> result = new Dictionary<string,object>();
                result["messages"] = new Object[]{reply};

                return Json(result);
            }
            else
            {
                Response.StatusCode = 400;
                return Content("Unknown event");
            }
        }
    }
}

var express = require('express');
var bodyParser = require('body-parser');
var app = express();

var WEBHOOK_SECRET = "YOUR_WEBHOOK_SECRET_HERE";

app.post('/telerivet/webhook',
  bodyParser.urlencoded({ extended: true }),
  function(req, res) {
      var secret = req.body.secret;
      if (secret !== WEBHOOK_SECRET) {
          res.status(403).end();
          return;
      }

      if (req.body.event == 'incoming_message') {
        var content = req.body.content;
        var from_number = req.body.from_number;
        var phone_id = req.body.phone_id;

        // do something with the message, e.g. send an autoreply
        res.json({
          messages: [
            { content: "Thanks for your message!" }
          ]
        });
      }

      res.status(200).end();
  }
);

app.listen(8000);

Example

HTTP/1.1 200 OK
Content-Type: application/json
...

{
 "messages":[
  {
   "content":"Reply message text"
  },
  {
   "content":"Another message text",
   "to_number":"+16505550123",
   "route_id":"YOUR_PHONE_ID"
  },
  {
   "to_number":"*104*12312312*456#",
   "message_type":"ussd",
  }
 ]
}

Example

Custom Actions:

Your Webhook Script:

<?php
    $webhook_secret = 'YOUR_WEBHOOK_SECRET_HERE';

    if ($_POST['secret'] !== $webhook_secret)
    {
        header('HTTP/1.1 403 Forbidden');
        echo "Invalid webhook secret";
    }
    else
    {
        if ($_POST['event'] == 'incoming_message')
        {
            header("Content-Type: application/json");
            echo json_encode([
                'variables' => [
                    'contact.name' => "John Smith",
                    '$foo' => 42,
                ]
            ]);
        }
    }

from django.views.decorators.csrf import csrf_exempt
from django.http import HttpResponse
import json

@csrf_exempt
def webhook(request):
    webhook_secret = 'YOUR_WEBHOOK_SECRET_HERE'

    if request.POST.get('secret') != webhook_secret:
        return HttpResponse("Invalid webhook secret", 'text/plain', 403)

    if request.POST.get('event') == 'incoming_message':
        return HttpResponse(json.dumps({
            'variables': {
                'contact.name': "John Smith",
                '$foo': 42
            }
        }), 'application/json')

/*
 *  Sample code depends on the Java JSON library:
 *    http://mvnrepository.com/artifact/org.json/json/20090211
 */
import java.io.IOException;
import java.io.PrintWriter;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import org.json.JSONArray;
import org.json.JSONException;
import org.json.JSONObject;

public class WebhookStatusServlet extends HttpServlet
{
    @Override
    protected void doPost(HttpServletRequest request, HttpServletResponse response)
            throws ServletException, IOException {

        PrintWriter out = response.getWriter();

        String webhookSecret = "YOUR_WEBHOOK_SECRET_HERE";

        if (!webhookSecret.equals(request.getParameter("secret")))
        {
            response.setStatus(403);
            out.write("Invalid webhook secret");
        }
        else if ("incoming_message".equals(request.getParameter("event")))
        {
            response.setContentType("application/json");
            try
            {
                JSONObject variables = new JSONObject();
                reply.put("$foo", 42);
                reply.put("contact.name", "John Smith");

                JSONObject json = new JSONObject();
                json.put("variables", variables);

                json.write(out);
            }
            catch (JSONException ex)
            {
                throw new ServletException(ex);
            }
        }
    }
}

using System;
using System.Collections.Generic;
using System.Web;
using System.Web.Mvc;

namespace MyMVCApplication.Controllers
{
    public class HomeController : Controller
    {
        public ActionResult Index()
        {
            String statusSecret = "YOUR_STATUS_SECRET_HERE";

            if (Request["secret"] != statusSecret)
            {
                Response.StatusCode = 403;
                return Content("Invalid status secret");
            }

            if (Request["event"] == "incoming_message")
            {
                Dictionary<string,object> variables = new Dictionary<string,object>();
                variables["$foo"] = 42;
                variables["contact.name"] = "John Smith";

                Dictionary<string,object> result = new Dictionary<string,object>();
                result["variables"] = variables;

                return Json(result);
            }
            else
            {
                Response.StatusCode = 400;
                return Content("Unknown event");
            }
        }
    }
}

var express = require('express');
var bodyParser = require('body-parser');
var app = express();

var WEBHOOK_SECRET = "YOUR_WEBHOOK_SECRET_HERE";

app.post('/telerivet/webhook',
  bodyParser.urlencoded({ extended: true }),
  function(req, res) {
      var secret = req.body.secret;
      if (secret !== WEBHOOK_SECRET) {
          res.status(403).end();
          return;
      }

      if (req.body.event == 'incoming_message') {
        res.json({
          variables: {
            'contact.name': "John Smith",
            '$foo': 42
          }
        });
      }

      res.status(200).end();
  }
);

app.listen(8000);

Example

<?php
    $webhook_secret = 'YOUR_WEBHOOK_SECRET_HERE';

    if ($_POST['secret'] !== $webhook_secret)
    {
        header('HTTP/1.1 403 Forbidden');
        echo "Invalid webhook secret";
    }
    else
    {
        if ($_POST['event'] == 'send_status')
        {
            $id = $_POST['id'];
            $status = $_POST['status'];
            $error_message = $_POST['error_message'];

            // do something with the message status, e.g. update your database
        }
    }

from django.views.decorators.csrf import csrf_exempt
from django.http import HttpResponse
import json

@csrf_exempt
def webhook(request):
    webhook_secret = 'YOUR_WEBHOOK_SECRET_HERE'

    if request.POST.get('secret') != webhook_secret:
        return HttpResponse("Invalid webhook secret", 'text/plain', 403)

    if request.POST.get('event') == 'send_status':
        id = request.POST.get('id')
        status = request.POST.get('status')
        error_message = request.POST.get('error_message')

        # do something with the message status, e.g. update your database

/*
 *  Sample code depends on the Java JSON library:
 *    http://mvnrepository.com/artifact/org.json/json/20090211
 */
import java.io.IOException;
import java.io.PrintWriter;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import org.json.JSONArray;
import org.json.JSONException;
import org.json.JSONObject;

public class WebhookStatusServlet extends HttpServlet
{
    @Override
    protected void doPost(HttpServletRequest request, HttpServletResponse response)
            throws ServletException, IOException {

        PrintWriter out = response.getWriter();

        String webhookSecret = "YOUR_WEBHOOK_SECRET_HERE";

        if (!webhookSecret.equals(request.getParameter("secret")))
        {
            response.setStatus(403);
            out.write("Invalid webhook secret");
        }
        else if ("send_status".equals(request.getParameter("event")))
        {
            String id = request.getParameter("id");
            String status = request.getParameter("status");
            String errorMessage = request.getParameter("error_message");

            // do something with the message, e.g. update your database
        }
    }
}

using System;
using System.Collections.Generic;
using System.Web;
using System.Web.Mvc;

namespace MyMVCApplication.Controllers
{
    public class HomeController : Controller
    {
        public ActionResult Index()
        {
            String statusSecret = "YOUR_STATUS_SECRET_HERE";

            if (Request["secret"] != statusSecret)
            {
                Response.StatusCode = 403;
                return Content("Invalid status secret");
            }

            if (Request["event"] == "send_status")
            {
                String id = Request["id"];
                String status = Request["status"];
                String errorMessage = Request["error_message"];

                // do something with the message status, e.g. update your database
                return Content("");
            }
            else
            {
                Response.StatusCode = 400;
                return Content("Unknown event");
            }
        }
    }
}

var express = require('express');
var bodyParser = require('body-parser');
var app = express();

var WEBHOOK_SECRET = "YOUR_WEBHOOK_SECRET_HERE";

app.post('/telerivet/webhook',
  bodyParser.urlencoded({ extended: true }),
  function(req, res) {
      var secret = req.body.secret;
      if (secret !== WEBHOOK_SECRET) {
          res.status(403).end();
          return;
      }

      if (req.body.event == 'send_status') {
        var id = req.body.id;
        var status = req.body.status;
        var error_message = req.body.error_message;

        // do something with the message status, e.g. update your database
      }

      res.status(200).end();
  }
);

app.listen(8000);

Example

<?php
    $webhook_secret = 'YOUR_WEBHOOK_SECRET_HERE';

    if ($_POST['secret'] !== $webhook_secret)
    {
        header('HTTP/1.1 403 Forbidden');
        echo "Invalid webhook secret";
    }
    else
    {
        if ($_POST['event'] == 'send_broadcast')
        {
            $id = $_POST['id'];
            $estimated_count = (int)$_POST['estimated_count'];
            $recipients_str = $_POST['recipients_str'];
            $content = $_POST['content'];

            // do something with the broadcast, e.g. update your database
        }
    }

from django.views.decorators.csrf import csrf_exempt
from django.http import HttpResponse
import json

@csrf_exempt
def webhook(request):
    webhook_secret = 'YOUR_WEBHOOK_SECRET_HERE'

    if request.POST.get('secret') != webhook_secret:
        return HttpResponse("Invalid webhook secret", 'text/plain', 403)

    if request.POST.get('event') == 'send_broadcast':
        id = request.POST.get('id')
        estimated_count = int(request.POST.get('estimated_count'))
        recipients_str = request.POST.get('recipients_str')
        content = request.POST.get('content')

        # do something with the broadcast, e.g. update your database

/*
 *  Sample code depends on the Java JSON library:
 *    http://mvnrepository.com/artifact/org.json/json/20090211
 */
import java.io.IOException;
import java.io.PrintWriter;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import org.json.JSONArray;
import org.json.JSONException;
import org.json.JSONObject;

public class WebhookStatusServlet extends HttpServlet
{
    @Override
    protected void doPost(HttpServletRequest request, HttpServletResponse response)
            throws ServletException, IOException {

        PrintWriter out = response.getWriter();

        String webhookSecret = "YOUR_WEBHOOK_SECRET_HERE";

        if (!webhookSecret.equals(request.getParameter("secret")))
        {
            response.setStatus(403);
            out.write("Invalid webhook secret");
        }
        else if ("send_broadcast".equals(request.getParameter("event")))
        {
        }
    }
}

using System;
using System.Collections.Generic;
using System.Web;
using System.Web.Mvc;

namespace MyMVCApplication.Controllers
{
    public class HomeController : Controller
    {
        public ActionResult Index()
        {
            String statusSecret = "YOUR_STATUS_SECRET_HERE";

            if (Request["secret"] != statusSecret)
            {
                Response.StatusCode = 403;
                return Content("Invalid status secret");
            }

            if (Request["event"] == "send_broadcast")
            {
            }
            else
            {
                Response.StatusCode = 400;
                return Content("Unknown event");
            }
        }
    }
}

var express = require('express');
var bodyParser = require('body-parser');
var app = express();

var WEBHOOK_SECRET = "YOUR_WEBHOOK_SECRET_HERE";

app.post('/telerivet/webhook',
  bodyParser.urlencoded({ extended: true }),
  function(req, res) {
      var secret = req.body.secret;
      if (secret !== WEBHOOK_SECRET) {
          res.status(403).end();
          return;
      }

      if (req.body.event == 'send_broadcast') {
      }

      res.status(200).end();
  }
);

app.listen(8000);