add sms messaging support

2025-12-19 05:47:46 +00:00 · 2020-10-09 08:04:39 -04:00
parent 53763aae14
commit ea64fb1a58
15 changed files with 445 additions and 58 deletions
--- a/app.js
+++ b/app.js
@@ -1,7 +1,11 @@
 const assert = require('assert');
 const opts = Object.assign({
-  timestamp: () => {return `, "time": "${new Date().toISOString()}"`;}
-}, {level: process.env.JAMBONES_LOGLEVEL || 'info'});
+  timestamp: () => {
+    return `, "time": "${new Date().toISOString()}"`;
+  }
+}, {
+  level: process.env.JAMBONES_LOGLEVEL || 'info'
+});
 const logger = require('pino')(opts);
 const express = require('express');
 const app = express();
@@ -28,7 +32,9 @@ const {
 }, logger);
 const {
  lookupAppBySid,
-  lookupAccountBySid
+  lookupAccountBySid,
+  lookupAccountByPhoneNumber,
+  lookupAppByPhoneNumber
 } = require('@jambonz/db-helpers')({
  host: process.env.JAMBONES_MYSQL_HOST,
  user: process.env.JAMBONES_MYSQL_USER,
@@ -49,7 +55,9 @@ Object.assign(app.locals, {
  purgeCalls,
  retrieveSet,
  lookupAppBySid,
-  lookupAccountBySid
+  lookupAccountBySid,
+  lookupAccountByPhoneNumber,
+  lookupAppByPhoneNumber
 });

 const unless = (paths, middleware) => {
@@ -60,13 +68,19 @@ const unless = (paths, middleware) => {
 };

 app.use(cors());
-app.use(express.urlencoded({ extended: true }));
+app.use(express.urlencoded({
+  extended: true
+}));
 app.use(express.json());
-app.use('/v1', unless(['/login', '/Users'], passport.authenticate('bearer', { session: false })));
+app.use('/v1', unless(['/login', '/Users', '/messaging', '/outboundSMS'], passport.authenticate('bearer', {
+  session: false
+})));
 app.use('/', routes);
 app.use((err, req, res, next) => {
  logger.error(err, 'burped error');
-  res.status(err.status || 500).json({msg: err.message});
+  res.status(err.status || 500).json({
+    msg: err.message
+  });
 });
 logger.info(`listening for HTTP traffic on port ${PORT}`);
 app.listen(PORT);
--- a/db/jambones-sql.sql
+++ b/db/jambones-sql.sql
@@ -148,8 +148,9 @@ CREATE TABLE applications
 application_sid CHAR(36) NOT NULL UNIQUE ,
 name VARCHAR(64) NOT NULL,
 account_sid CHAR(36) NOT NULL COMMENT 'account that this application belongs to',
-call_hook_sid CHAR(36) COMMENT 'webhook to call for inbound calls to phone numbers owned by this account',
+call_hook_sid CHAR(36) COMMENT 'webhook to call for inbound calls ',
 call_status_hook_sid CHAR(36) COMMENT 'webhook to call for call status events',
+messaging_hook_sid CHAR(36) COMMENT 'webhook to call for inbound SMS/MMS ',
 speech_synthesis_vendor VARCHAR(64) NOT NULL DEFAULT 'google',
 speech_synthesis_language VARCHAR(12) NOT NULL DEFAULT 'en-US',
 speech_synthesis_voice VARCHAR(64),
@@ -242,6 +243,8 @@ ALTER TABLE applications ADD FOREIGN KEY call_hook_sid_idxfk (call_hook_sid) REF

 ALTER TABLE applications ADD FOREIGN KEY call_status_hook_sid_idxfk (call_status_hook_sid) REFERENCES webhooks (webhook_sid);

+ALTER TABLE applications ADD FOREIGN KEY messaging_hook_sid_idxfk (messaging_hook_sid) REFERENCES webhooks (webhook_sid);
+
 CREATE INDEX service_provider_sid_idx ON service_providers (service_provider_sid);
 CREATE INDEX name_idx ON service_providers (name);
 CREATE INDEX root_domain_idx ON service_providers (root_domain);
--- a/db/jambones.sqs
+++ b/db/jambones.sqs
@@ -194,11 +194,13 @@
        <SQLField>
            <name><![CDATA[expires_at]]></name>
            <type><![CDATA[TIMESTAMP]]></type>
+            <defaultValue><![CDATA[NULL]]></defaultValue>
            <uid><![CDATA[DE86BC18-858E-4D7E-9B83-891DB2861434]]></uid>
        </SQLField>
        <SQLField>
            <name><![CDATA[last_used]]></name>
            <type><![CDATA[TIMESTAMP]]></type>
+            <defaultValue><![CDATA[NULL]]></defaultValue>
            <uid><![CDATA[11A93288-B892-436B-9BB4-D5C3B70DB061]]></uid>
        </SQLField>
        <SQLField>
@@ -764,7 +766,7 @@
        </location>
        <size>
            <width>345.00</width>
-            <height>240.00</height>
+            <height>260.00</height>
        </size>
        <zorder>0</zorder>
        <SQLField>
@@ -812,7 +814,7 @@
            <destinationCardinality>2</destinationCardinality>
            <referencesFieldUID><![CDATA[E046BA30-BC18-483C-A5C8-766E7160F574]]></referencesFieldUID>
            <referencesTableUID><![CDATA[64D64CB9-0990-4C68-BE71-F9FD43C2BE19]]></referencesTableUID>
-            <objectComment><![CDATA[webhook to call for inbound calls to phone numbers owned by this account]]></objectComment>
+            <objectComment><![CDATA[webhook to call for inbound calls ]]></objectComment>
            <uid><![CDATA[55AE0F31-209A-49F9-A6CB-1BB31BE4178A]]></uid>
        </SQLField>
        <SQLField>
@@ -829,6 +831,20 @@
            <objectComment><![CDATA[webhook to call for call status events]]></objectComment>
            <uid><![CDATA[A3B4621B-DF13-4920-A718-068B20CB4E8A]]></uid>
        </SQLField>
+        <SQLField>
+            <name><![CDATA[messaging_hook_sid]]></name>
+            <type><![CDATA[CHAR(36)]]></type>
+            <referencesField>webhook_sid</referencesField>
+            <referencesTable>webhooks</referencesTable>
+            <referencesField><![CDATA[webhook_sid]]></referencesField>
+            <referencesTable><![CDATA[webhooks]]></referencesTable>
+            <sourceCardinality>4</sourceCardinality>
+            <destinationCardinality>1</destinationCardinality>
+            <referencesFieldUID><![CDATA[E046BA30-BC18-483C-A5C8-766E7160F574]]></referencesFieldUID>
+            <referencesTableUID><![CDATA[64D64CB9-0990-4C68-BE71-F9FD43C2BE19]]></referencesTableUID>
+            <objectComment><![CDATA[webhook to call for inbound SMS/MMS ]]></objectComment>
+            <uid><![CDATA[4690A98A-2F67-4205-A5C1-D9523F6B3282]]></uid>
+        </SQLField>
        <SQLField>
            <name><![CDATA[speech_synthesis_vendor]]></name>
            <type><![CDATA[VARCHAR(64)]]></type>
@@ -1083,17 +1099,17 @@
        <overviewPanelHidden><![CDATA[0]]></overviewPanelHidden>
        <pageBoundariesVisible><![CDATA[0]]></pageBoundariesVisible>
        <PageGridVisible><![CDATA[0]]></PageGridVisible>
-        <RightSidebarWidth><![CDATA[1944.000000]]></RightSidebarWidth>
+        <RightSidebarWidth><![CDATA[1924.000000]]></RightSidebarWidth>
        <sidebarIndex><![CDATA[2]]></sidebarIndex>
        <snapToGrid><![CDATA[0]]></snapToGrid>
        <SourceSidebarWidth><![CDATA[0.000000]]></SourceSidebarWidth>
        <SQLEditorFileFormatVersion><![CDATA[4]]></SQLEditorFileFormatVersion>
        <uid><![CDATA[58C99A00-06C9-478C-A667-C63842E088F3]]></uid>
-        <windowHeight><![CDATA[1194.000000]]></windowHeight>
-        <windowLocationX><![CDATA[26.000000]]></windowLocationX>
-        <windowLocationY><![CDATA[100.000000]]></windowLocationY>
+        <windowHeight><![CDATA[1013.000000]]></windowHeight>
+        <windowLocationX><![CDATA[2716.000000]]></windowLocationX>
+        <windowLocationY><![CDATA[1913.000000]]></windowLocationY>
        <windowScrollOrigin><![CDATA[{0, 5}]]></windowScrollOrigin>
-        <windowWidth><![CDATA[2221.000000]]></windowWidth>
+        <windowWidth><![CDATA[2201.000000]]></windowWidth>
    </SQLDocumentInfo>
    <AllowsIndexRenamingOnInsert><![CDATA[1]]></AllowsIndexRenamingOnInsert>
    <defaultLabelExpanded><![CDATA[1]]></defaultLabelExpanded>
--- a/lib/models/application.js
+++ b/lib/models/application.js
@@ -1,29 +1,13 @@
 const Model = require('./model');
 const {getMysqlConnection} = require('../db');
-const listSqlSp = `
-SELECT * from applications
-WHERE account_sid in (
-  SELECT account_sid from accounts
-  WHERE service_provider_sid = ?
-)`;
-const listSqlAccount = 'SELECT * from applications WHERE account_sid = ?';
-const retrieveSqlSp = `
-SELECT * from applications
-WHERE account_sid in (
-  SELECT account_sid from accounts
-  WHERE service_provider_sid = ?
-)
-AND application_sid = ?`;
-const retrieveSqlAccount = `
-SELECT * from applications
-WHERE account_sid = ?
-AND application_sid = ?`;

 const retrieveSql = `SELECT * from applications app
 LEFT JOIN webhooks AS ch
 ON app.call_hook_sid = ch.webhook_sid
 LEFT JOIN webhooks AS sh
-ON app.call_status_hook_sid = sh.webhook_sid`;
+ON app.call_status_hook_sid = sh.webhook_sid 
+LEFT JOIN webhooks AS mh
+ON app.messaging_hook_sid = mh.webhook_sid`;

 function transmogrifyResults(results) {
  return results.map((row) => {
@@ -36,8 +20,13 @@ function transmogrifyResults(results) {
      Object.assign(obj, {call_status_hook: row.sh});
    }
    else obj.call_status_hook = null;
+    if (row.mh && Object.keys(row.mh).length && row.mh.url !== null) {
+      Object.assign(obj, {messaging_hook: row.mh});
+    }
+    else obj.messaging_hook = null;
    delete obj.call_hook_sid;
    delete obj.call_status_hook_sid;
+    delete obj.messaging_hook_sid;
    return obj;
  });
 }
@@ -123,12 +112,14 @@ Application.fields = [
  {
    name: 'call_hook_sid',
    type: 'string',
-    required: true
  },
  {
    name: 'call_status_hook_sid',
    type: 'string',
-    required: true
+  },
+  {
+    name: 'messaging_hook_sid',
+    type: 'string',
  }
 ];

--- a/lib/routes/api/accounts.js
+++ b/lib/routes/api/accounts.js
@@ -5,6 +5,7 @@ const Account = require('../../models/account');
 const Webhook = require('../../models/webhook');
 const ApiKey = require('../../models/api-key');
 const ServiceProvider = require('../../models/service-provider');
+const uuidv4 = require('uuid/v4');
 const decorate = require('./decorate');
 const snakeCase = require('../../utils/snake-case');
 const sysError = require('./error');
@@ -135,6 +136,30 @@ async function validateCreateCall(logger, sid, req) {
  }
 }

+async function validateCreateMessage(logger, sid, req) {
+  const obj = req.body;
+  const {lookupAccountByPhoneNumber} = req.app.locals;
+
+  if (req.user.account_sid !== sid) {
+    throw new DbErrorBadRequest(`unauthorized createMessage request for account ${sid}`);
+  }
+
+  if (!obj.from) throw new DbErrorBadRequest('missing from property');
+  else {
+    const regex = /^\+(\d+)$/;
+    const arr = regex.exec(obj.from);
+    const from = arr ? arr[1] : obj.from;
+    const account = await lookupAccountByPhoneNumber(from);
+    if (!account) throw new DbErrorBadRequest(`accountSid ${sid} does not own phone number ${from}`);
+  }
+
+  if (!obj.to) throw new DbErrorBadRequest('missing to property');
+
+  if (!obj.text && !obj.media) {
+    throw new DbErrorBadRequest('either text or media required in outbound message');
+  }
+}
+
 async function validateAdd(req) {
  /* account-level token can not be used to add accounts */
  if (req.user.hasAccountAuth) {
@@ -420,5 +445,47 @@ router.post('/:sid/Calls/:callSid', async(req, res) => {
  }
 });

+/**
+ * create a new Message
+ */
+router.post('/:sid/Messages', async(req, res) => {
+  const sid = req.params.sid;
+  const setName = `${(process.env.JAMBONES_CLUSTER_ID || 'default')}:active-fs`;
+  const {retrieveSet, logger} = req.app.locals;
+
+  try {
+    const fs = await retrieveSet(setName);
+    if (0 === fs.length) {
+      logger.info('No available feature servers to handle createMessage API request');
+      return res.json({msg: 'no available feature servers at this time'}).status(500);
+    }
+    const ip = fs[idx++ % fs.length];
+    logger.info({fs}, `feature servers available for createMessage API request, selecting ${ip}`);
+    const serviceUrl = `http://${ip}:3000/v1/createMessage/${sid}`;
+    await validateCreateMessage(logger, sid, req);
+
+    const payload = Object.assign({messageSid: uuidv4()}, req.body);
+    logger.debug({payload}, `sending createMessage API request to to ${ip}`);
+    updateLastUsed(logger, sid, req).catch((err) => {});
+    request({
+      url: serviceUrl,
+      method: 'POST',
+      json: true,
+      body: payload
+    }, (err, response, body) => {
+      if (err) {
+        logger.error(err, `Error sending createMessage POST to ${ip}`);
+        return res.sendStatus(500);
+      }
+      if (response.statusCode !== 200) {
+        logger.error({statusCode: response.statusCode}, `Non-success response returned by createMessage ${serviceUrl}`);
+        return res.sendStatus(500);
+      }
+      res.status(201).json(body);
+    });
+  } catch (err) {
+    sysError(logger, res, err);
+  }
+});

 module.exports = router;
--- a/lib/routes/api/applications.js
+++ b/lib/routes/api/applications.js
@@ -62,7 +62,7 @@ router.post('/', async(req, res) => {

    // create webhooks if provided
    const obj = Object.assign({}, req.body);
-    for (const prop of ['call_hook', 'call_status_hook']) {
+    for (const prop of ['call_hook', 'call_status_hook', 'messaging_hook']) {
      if (obj[prop]) {
        obj[`${prop}_sid`] = await Webhook.make(obj[prop]);
        delete obj[prop];
@@ -113,7 +113,7 @@ router.put('/:sid', async(req, res) => {

    // create webhooks if provided
    const obj = Object.assign({}, req.body);
-    for (const prop of ['call_hook', 'call_status_hook']) {
+    for (const prop of ['call_hook', 'call_status_hook', 'messaging_hook']) {
      if (prop in obj && Object.keys(obj[prop]).length) {
        if ('webhook_sid' in obj[prop]) {
          const sid = obj[prop]['webhook_sid'];
--- a/lib/routes/api/index.js
+++ b/lib/routes/api/index.js
@@ -20,4 +20,8 @@ api.use('/Sbcs', isAdminScope, require('./sbcs'));
 api.use('/Users', require('./users'));
 api.use('/login', require('./login'));

+// messaging
+api.use('/messaging', require('./sms-inbound'));      // inbound SMS from carrier
+api.use('/outboundSMS', require('./sms-outbound'));   // outbound SMS from feature server
+
 module.exports = api;
--- a/lib/routes/api/phone-numbers.js
+++ b/lib/routes/api/phone-numbers.js
@@ -31,13 +31,13 @@ async function validateAdd(req) {
 async function checkInUse(req, sid) {
  const phoneNumber = await PhoneNumber.retrieve(sid);
  if (phoneNumber.account_sid) {
-    throw new DbErrorUnprocessableRequest('cannot delete phone number that is assigned to an account');  
+    throw new DbErrorUnprocessableRequest('cannot delete phone number that is assigned to an account');
  }
 }

 /* can not change number or voip carrier */
 async function validateUpdate(req, sid) {
-  const result = await PhoneNumber.retrieve(sid);
+  //const result = await PhoneNumber.retrieve(sid);
  if (req.body.voip_carrier_sid) throw new DbErrorBadRequest('voip_carrier_sid may not be modified');
  if (req.body.number) throw new DbErrorBadRequest('number may not be modified');

--- a/lib/routes/api/service-providers.js
+++ b/lib/routes/api/service-providers.js
@@ -97,6 +97,4 @@ router.put('/:sid', async(req, res) => {
  }
 });

-
-
 module.exports = router;
--- a/lib/routes/api/sms-inbound.js
+++ b/lib/routes/api/sms-inbound.js
@@ -0,0 +1,142 @@
+const router = require('express').Router();
+const request = require('request');
+const getProvider = require('../../utils/sms-provider');
+const uuidv4 = require('uuid/v4');
+const sysError = require('./error');
+let idx = 0;
+
+
+async function doSendResponse(res, respondFn, body) {
+  if (typeof respondFn === 'number') res.sendStatus(respondFn);
+  else if (typeof respondFn !== 'function') res.sendStatus(200);
+  else {
+    const payload = await respondFn(body);
+    res.status(200).json(payload);
+  }
+}
+
+router.post('/:provider', async(req, res) => {
+  const provider = req.params.provider;
+  const {
+    retrieveSet,
+    lookupAppByPhoneNumber,
+    logger
+  } = req.app.locals;
+  const setName = `${process.env.JAMBONES_CLUSTER_ID || 'default'}:active-fs`;
+  logger.debug({path: req.path, body: req.body}, 'incomingSMS from carrier');
+
+  // search for provider module
+  const arr = getProvider(logger, provider);
+  if (!arr) {
+    logger.info({body: req.body, params: req.params},
+      `rejecting incomingSms request from unknown provider ${provider}`
+    );
+    return res.sendStatus(404);
+  }
+
+  const providerData = arr[1];
+  if (!providerData || !providerData.module) {
+    logger.info({body: req.body, params: req.params},
+      `rejecting incomingSms request from badly configured provider ${provider}`
+    );
+    return res.sendStatus(404);
+  }
+
+  // load provider module
+  let filterFn, respondFn;
+  try {
+    const {
+      fromProviderFormat,
+      formatProviderResponse
+    } = require(providerData.module);
+    // must at least provide a filter function
+    if (!fromProviderFormat) {
+      logger.info(
+        `missing fromProviderFormat function in module ${providerData.module} for provider ${provider}`
+      );
+      return res.sendStatus(404);
+    }
+    filterFn = fromProviderFormat;
+    respondFn = formatProviderResponse;
+  } catch (err) {
+    logger.info(
+      err,
+      `failure loading module ${providerData.module} for provider ${provider}`
+    );
+    return res.sendStatus(500);
+  }
+
+  try {
+    const fs = await retrieveSet(setName);
+    if (0 === fs.length) {
+      logger.info('No available feature servers to handle createCall API request');
+      return res
+        .json({
+          msg: 'no available feature servers at this time'
+        })
+        .status(480);
+    }
+    const ip = fs[idx++ % fs.length];
+    const serviceUrl = `http://${ip}:3000/v1/messaging/${provider}`;
+    const messageSid = uuidv4();
+    const payload = await Promise.resolve(filterFn({messageSid}, req.body));
+
+    /**
+     * lookup the application associated with the number in the To field
+     * since there could be multiple Tos, we have to search through (and cc also)
+     */
+    let app;
+    const to = Array.isArray(payload.to) ? payload.to : [payload.to];
+    const cc = Array.isArray(payload.cc) ? payload.cc : (payload.cc ? [payload.cc] : []);
+    const dids = to.concat(cc).filter((n) => n.length);
+    for (let did of dids) {
+      const regex = /^\+(\d+)$/;
+      const arr = regex.exec(did);
+      did = arr ? arr[1] : did;
+      const obj = await lookupAppByPhoneNumber(did);
+      logger.info({obj}, `lookup app for phone number ${did}`);
+      if (obj) {
+        logger.info({did, obj}, 'Found app for DID');
+        app = obj;
+        break;
+      }
+    }
+    if (!app) {
+      logger.info({payload}, 'No application found for incoming SMS');
+      return res.sendStatus(404);
+    }
+    if (!app.messaging_hook) {
+      logger.info({payload}, `app "${app.name}" found for incoming SMS does not have an associated messaging hook`);
+      return res.sendStatus(404);
+    }
+    payload.app = app;
+
+    logger.debug({body: req.body, payload}, 'filtered incoming SMS');
+
+    logger.info({payload, url: serviceUrl}, `sending incomingSms API request to FS at ${ip}`);
+
+    request({
+      url: serviceUrl,
+      method: 'POST',
+      json: true,
+      body: payload,
+    },
+    async(err, response, body) => {
+      if (err) {
+        logger.error(err, `Error sending incomingSms POST to ${ip}`);
+        return res.sendStatus(500);
+      }
+      if (200 === response.statusCode) {
+        // success
+        logger.info({body}, 'sending response to provider for incomingSMS');
+        return doSendResponse(res, respondFn, body);
+      }
+      logger.error({statusCode: response.statusCode}, `Non-success response returned by incomingSms ${ip}`);
+      return res.sendStatus(500);
+    });
+  } catch (err) {
+    sysError(logger, res, err);
+  }
+});
+
+module.exports = router;
--- a/lib/routes/api/sms-outbound.js
+++ b/lib/routes/api/sms-outbound.js
@@ -0,0 +1,44 @@
+const router = require('express').Router();
+const getProvider = require('../../utils/sms-provider');
+const sysError = require('./error');
+
+router.post('/', async(req, res) => {
+  const { logger } = req.app.locals;
+
+  try {
+    // if provider specified use it, otherwise use first in list
+    const arr = getProvider(logger, req.body.provider);
+    if (!Array.isArray(arr)) {
+      throw new Error('outboundSMS - unable to locate sms provider to use to send message');
+    }
+
+    const providerData = arr[1];
+    if (!providerData || !providerData.module) {
+      throw new Error(`rejecting outgoingSms request for unknown or badly configured provider ${req.body.provider}`);
+    }
+
+    const provider = arr[0];
+    const opts = providerData.options;
+    if (!opts || !opts.url) {
+      throw new Error(`rejecting outgoingSms request -- no HTTP url for ${req.body.provider}`);
+    }
+
+    // load provider module
+    const { sendSms } = require(providerData.module);
+    if (!sendSms) {
+      throw new Error(`missing sendSms function in module ${providerData.module} for provider ${provider}`);
+    }
+
+    // send the SMS
+    const payload = req.body;
+    delete payload.provider;
+    logger.debug({opts, payload}, `outboundSMS - sending to ${opts.url}`);
+    const response = await sendSms(opts, payload);
+    logger.info({response, payload: req.body}, `outboundSMS - sent to ${opts.url}`);
+    res.status(200).json(response);
+  } catch (err) {
+    sysError(logger, res, err);
+  }
+});
+
+module.exports = router;
--- a/lib/swagger/swagger.yaml
+++ b/lib/swagger/swagger.yaml
@@ -1249,10 +1249,13 @@ paths:
                  format: uuid
                call_hook:
                  $ref: '#/components/schemas/Webhook'
-                  description: authentication webhook for inbound calls from PSTN
+                  description: application webhook to handle inbound voice calls
                call_status_hook:
                  $ref: '#/components/schemas/Webhook'
-                  description: webhook for call status events
+                  description: webhook to report call status events
+                messaging_hook:
+                  $ref: '#/components/schemas/Webhook'
+                  description: application webhook to handle inbound SMS/MMS messages
                speech_synthesis_vendor:
                  type: string
                speech_synthesis_voice:
@@ -1433,9 +1436,9 @@ paths:
            application/json:
              schema:
                required:
-                  - callSid
+                  - sid
                properties:
-                  callSid:
+                  sid:
                    type: string
                    format: uuid
                    example: 2531329f-fb09-4ef7-887e-84e648214436
@@ -1465,8 +1468,6 @@ paths:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
-
-
  /Accounts/{AccountSid}/Calls/{CallSid}:
    parameters:
      - name: AccountSid
@@ -1567,7 +1568,39 @@ paths:
          content:
            application/json:
              schema:
-                $ref: '#/components/schemas/GeneralError'                
+                $ref: '#/components/schemas/GeneralError'
+  /Accounts/{AccountSid}/Messages:
+    post:
+      summary: create an outgoing SMS message
+      operationId: createMessage
+      parameters:
+      - name: AccountSid
+        in: path
+        required: true
+        schema:
+          type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Message'
+      responses:
+        201:
+          description: call successfully created
+          content:
+            application/json:
+              schema:
+                required:
+                  - sid
+                properties:
+                  sid:
+                    type: string
+                    format: uuid
+                    example: 2531329f-fb09-4ef7-887e-84e648214436
+                  providerResponse:
+                    type: string
+        400:
+          description: bad request         
 components:
  securitySchemes:
    bearerAuth:
@@ -1715,10 +1748,13 @@ components:
          format: uuid
        call_hook:
          $ref: '#/components/schemas/Webhook'
-          description: authentication webhook for registration
+          description: application webhook for inbound voice calls
        call_status_hook:
          $ref: '#/components/schemas/Webhook'
-          description: authentication webhook for registration
+          description: webhhok for reporting call status events
+        messaging_hook:
+          $ref: '#/components/schemas/Webhook'
+          description: application webhook for inbound SMS/MMS
        speech_synthesis_vendor:
          type: string
        speech_synthesis_voice:
@@ -1731,8 +1767,6 @@ components:
        - application_sid
        - name
        - account_sid
-        - inbound_hook
-        - inbound_status_hook
    ApiKey:
      type: object
      properties:
@@ -1914,6 +1948,22 @@ components:
      required:
        - type
      example: {"type": "phone", "number": "+16172375080"}
+    Message:
+      properties:
+        provider:
+          type: string
+        from:
+          type: string
+        to:
+          type: string
+        text:
+          type: string
+        media:
+          type: string
+      required:
+        - from
+        - to
+      example: {"from": "13394445678", "to": "16173333456", "text": "please call when you can"}

 security:
  - bearerAuth: []
--- a/lib/utils/sms-provider.js
+++ b/lib/utils/sms-provider.js
@@ -0,0 +1,40 @@
+const providers = new Map();
+let init = false;
+
+function initProviders(logger) {
+  if (init) return;
+  if (process.env.JAMBONES_MESSAGING) {
+    try {
+      const obj = JSON.parse(process.env.JAMBONES_MESSAGING);
+      for (const [key, value] of Object.entries(obj)) {
+        logger.debug({config: value}, `Adding SMS provider ${key}`);
+        providers.set(key, value);
+      }
+      logger.info(`Configured ${providers.size} SMS providers`);
+    } catch (err) {
+      logger.error(err, `expected JSON for JAMBONES_MESSAGING : ${process.env.JAMBONES_MESSAGING}`);
+    }
+  }
+  else {
+    logger.info('no JAMBONES_MESSAGING env var, messaging is disabled');
+  }
+  init = true;
+}
+
+function getProvider(logger, partner) {
+  initProviders(logger);
+  if (typeof partner === 'string') {
+    const config = providers.get(partner);
+    const arr = [partner, config];
+    logger.debug({arr}, 'getProvider by name');
+    return arr;
+  }
+  else if (providers.size) {
+    const arr = providers.entries().next().value;
+    logger.debug({arr}, 'getProvider by first available');
+    return arr;
+  }
+}
+
+module.exports = getProvider;
+
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
  "name": "jambonz-api-server",
-  "version": "1.1.7",
+  "version": "1.2.0",
  "description": "",
  "main": "app.js",
  "scripts": {
@@ -15,8 +15,11 @@
    "url": "https://github.com/jambonz/jambonz-api-server.git"
  },
  "dependencies": {
-    "@jambonz/db-helpers": "^0.3.8",
-    "@jambonz/realtimedb-helpers": "0.2.15",
+    "@jambonz/db-helpers": "^0.5.1",
+    "@jambonz/messaging-382com": "0.0.2",
+    "@jambonz/messaging-peerless": "0.0.9",
+    "@jambonz/messaging-simwood": "0.0.4",
+    "@jambonz/realtimedb-helpers": "0.2.17",
    "cors": "^2.8.5",
    "express": "^4.17.1",
    "mysql2": "^2.1.0",
@@ -25,17 +28,18 @@
    "pino": "^5.17.0",
    "request": "^2.88.2",
    "request-debug": "^0.2.0",
+    "swagger-ui-dist": "^3.35.0",
    "swagger-ui-express": "^4.1.4",
    "uuid": "^3.4.0",
    "yamljs": "^0.3.0"
  },
  "devDependencies": {
-    "eslint": "^6.8.0",
+    "eslint": "^7.10.0",
    "eslint-plugin-promise": "^4.2.1",
    "nyc": "^15.1.0",
    "request-promise-native": "^1.0.9",
    "tap-dot": "^2.0.0",
    "tap-spec": "^5.0.0",
-    "tape": "^4.13.3"
+    "tape": "^5.0.1"
  }
 }
--- a/test/applications.js
+++ b/test/applications.js
@@ -38,6 +38,9 @@ test('application tests', async(t) => {
        call_status_hook: {
          url: 'http://example.com/status',
          method: 'POST'
+        },
+        messaging_hook: {
+          url: 'http://example.com/sms'
        }
      }
    });
@@ -58,6 +61,7 @@ test('application tests', async(t) => {
      json: true,
    });
    t.ok(result[0].name === 'daveh' , 'successfully retrieved application by sid');
+    t.ok(result[0].messaging_hook.url === 'http://example.com/sms' , 'successfully retrieved messaging_hook from application');

    /* update applications */
    result = await request.put(`/Applications/${sid}`, {
@@ -67,11 +71,21 @@ test('application tests', async(t) => {
      body: {
        call_hook: {
          url: 'http://example2.com'
+        },
+        messaging_hook: {
+          url: 'http://example2.com/mms'
        }
      }
    });
    t.ok(result.statusCode === 204, 'successfully updated application');

+    /* validate messaging hook was updated */
+    result = await request.get(`/Applications/${sid}`, {
+      auth: authAdmin,
+      json: true,
+    });
+    t.ok(result[0].messaging_hook.url === 'http://example2.com/mms' , 'successfully updated messaging_hook');
+    
    /* assign phone number to application */
    result = await request.put(`/PhoneNumbers/${phone_number_sid}`, {
      auth: authAdmin,