3CX 线路要求（下）

813 阅读量

在上篇文章中，我们介绍了对接 3CX 的 SIP 线路拨打电话有哪些必需的参数。今天我们来介绍对接 3CX 线路的可选项。

可选项

E164 号码格式

除非线路支持 SMS/MMS 功能，否则 E164 号码格式是可选项。反之则是必需项。

入站呼叫

呼叫送到 3CX 电话系统必须使用完整的 E164 号码格式（开头为+号）。3CX 系统可以设置从不同的 SIP header 读取号码。比较常用的字段为 To:UserPart 和 Request-Line URI: UserPart。

出站呼叫

客户最好能使用 E164 格式的号码进行外呼。同时他们最好也能把 Caller ID 也显示为 E164 格式。简而言之，From 和 To 字段的号码都需要是 E164 格式。

支持 TLS / SRTP

能支持 TLS 和 SRTP 是最好的，这也是客户日渐增长的需求之一。但目前它不是必需项，3CX StartUP 目前也不支持，但未来我们可能会考虑加入 TLS / SRTP。

在 3CX 配置 TLS/SRTP 的可以查看这篇文章：https://3x.58voip.com/sip-trunk-tls-srtp/

支持 T38

支持传真不是必须的。但目前还是有不少客户和市场依赖它。

3CX 支持 T38 和 G711 传真，我们更倾向于使用 T38。

关于传真的技术要求可以查看这篇文章：https://3x.58voip.com/sip-trunk-faxing/

SMS/MMS API

要求

  • 支持 E164
  • 有完整的文档：
    • 对于发送信息部分的 HTTPs REST API
    • 对于接收信息和状态报告的 HTTPs Webhook
  • 可以在 Provider Customer Portal 生成 API Key 并设置 Webhook
  • 与 SIP 线路的语音使用相同的号码

验证

线路供应商需要提供一个 API Key（随机生成的，足够长且每个账号独立的） 给到用户。3CX 的 GenericVoipProvider 需要使用这个 API Key 进行配置，3CX 系统会使用它来跟线路供应商完成验证的过程。3CX 电话系统会在下面的 Authorization header 中传递这个 key。

Authorization: Bearer <YOUR_API_KEY>

这是为了让线路供应商能够对来自 3CX 的用户请求进行身份验证和授权。

发送 SMS/MMS 请求

下面是 3CX 向线路的号码发送 SMS 短信的例子：

curl -X POST \  --header "Content-Type: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{
    "from": "+10987654321",
    "to": "+11234567890",
    "text": "Hello John, how are you?",
  }'\
https://api.generic.com/v2/messages

每一个字段都是必须的。其中字段 to 和 from 需要是 E.164 格式。

下面是 3CX 向供应商的号码发送彩信的例子：

curl -X POST "https://api.generic.com/v2/messages" \  --header "Content-Type: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{
    "from": "+10987654321",
    "to": "+11234567890",
    "subject": "Picture",
    "text": "Hello John, how are you?",
    "media_urls": [
    "https://3cx.com/path/123qweasd456rtg954mdf.png",
    ]
  }

Webhook 通知

供应商将使用配置的 webhook 的 POST 方法将收到的 SMS/MMS 消息和送达回执发送给 3CX。

下面是收到一条新的 SMS 信息的例子：

{  "data": {
    "event_type": "message.received",
    "id": "b301ed3f-1490-491f-995f-6e64e69674d4",
    "occurred_at": "2019-12-09T20:16:07.588+00:00",
    "payload": {
      "completed_at": null,
      "cost": null,
      "direction": "inbound",
      "encoding": "GSM-7",
      "errors": [],
      "from": {
        "carrier": "T-Mobile USA",
        "line_type": "long_code",
        "phone_number": "+1312500000",
        "status": "webhook_delivered"
      },
      "id": "84cca175-9755-4859-b67f-4730d7f58aa3",
      "media": [],
      "messaging_profile_id": "740572b6-099c-44a1-89b9-6c92163bc68d",
      "organization_id": "47a530f8-4362-4526-829b-bcee17fd9f7a",
      "parts": 1,
      "received_at": "2019-12-09T20:16:07.503+00:00",
      "record_type": "message",
      "sent_at": null,
      "tags": [],
      "text": "Hello from Generic!",
      "to": [
        {
          "carrier": "Generic",
          "line_type": "Wireless",
          "phone_number": "+1773005000",
          "status": "webhook_delivered"
        }
      ],
      "type": "SMS",
      "valid_until": null,
      "webhook_failover_url": null,
      "webhook_url": "http://webhook.site/04bbd2e3-09b5-4c9e-95de-a1debeb9e675"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "http://webhook.site/04bbd2e3-09b5-4c9e-95de-a1debeb9e675"
  }
}

如果有必要供应商可以对消息的字段进行扩充。但是下列字段是必需的：

  • data.id
  • data.event_type
  • data.payload.from.phone_number
  • data.payload.to.phone_number
  • data.payload.text
  • data.payload.received_at

其中 data.id 字段是供应商内部的消息 ID。字段 phone_number, from, to 需要是 E.164 格式的号码。

下面是收到一条新的 MMS 消息的例子：

{    "data": {
    "record_type": "message",
    "direction": "outbound",
    "id": "403186a2-4d6e-47a5-98c1-6eeba8fd1b4c",
    "type": "MMS",
    "organization_id": "9d69fdbd-c169-4bd1-903d-0db81d4550cf",
    "messaging_profile_id": "40017f96-ea51-4377-96d0-c84df8026ec9",
    "from": {
      "phone_number": "+17869412345",
      "carrier": "Generic",
      "line_type": "Wireless"
    },
    "to": [
      {
        "phone_number": "+18135712345",
        "status": "queued",
        "carrier": "....",
        "line_type": "Wireline"
      }
    ],
    "cc": [],
    "text": "",
    "media": [
      {
        "url": "https://somedomain.com:5001/myphone/downloadchatfile/3f68b2835f9f8d1de5f2192ee95bfc849a36ed356d3a864baa4f0b875cfe94c5.png",
        "content_type": null,
        "sha256": null,
        "size": null
      }
    ],
    "webhook_url": "https://somedomain.com:5001/sms/generic/2c2970fa-235e-4679-b0f0-3bac71faec2c",
    "webhook_failover_url": "",
    "encoding": "GSM-7",
    "parts": 1,
    "tags": [],
    "cost": {
      "amount": "0.0150",
      "currency": "USD"
    },
    "received_at": "2023-03-02T12:30:28.997+00:00",
    "sent_at": null,
    "completed_at": null,
    "valid_until": "2023-03-02T13:30:28.997+00:00",
    "errors": []
  }
}

如果 3CX 发送的短信送达成功了，将会收到下面例子中的消息：

{  "data": {
    "event_type": "message.finalized",
    "id": "4ee8c3a6-4995-4309-a3c6-38e3db9ea4be",
    "occurred_at": "2019-12-09T21:32:14.148+00:00",
    "payload": {
      "completed_at": "2019-12-09T21:32:14.148+00:00",
      "cost": null,
      "direction": "outbound",
      "encoding": "GSM-7",
      "errors": [],
      "from": {
        "carrier": "T-Mobile USA",
        "line_type": "Wireless",
        "phone_number": "+13125000000",
        "status": "webhook_delivered"
      },
      "id": "ac012cbf-5e09-46af-a69a-7c0e2d90993c",
      "media": [],
      "messaging_profile_id": "83d2343b-553f-4c5f-b8c8-fd27004f94bf",
      "organization_id": "9d76d591-1b7d-405d-8c64-1320ee070245",
      "parts": 1,
      "received_at": "2019-12-09T21:32:13.552+00:00",
      "record_type": "message",
      "sent_at": "2019-12-09T21:32:13.596+00:00",
      "tags": [],
      "text": "Hello there!",
      "to": [
        {
          "carrier": "T-MOBILE USA, INC.",
          "line_type": "Wireless",
          "phone_number": "+13125000000",
          "status": "delivered"
        }
      ],
      "type": "SMS",
      "valid_until": "2019-12-09T22:32:13.552+00:00",
      "webhook_failover_url": "",
      "webhook_url": "http://webhook.site/af3a92e7-e150-442c-9fe6-61658ce26b1a"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "http://webhook.site/af3a92e7-e150-442c-9fe6-61658ce26b1a"
  }
}

下列字段是必需的：

  • data.event_type （值可以是 message.finalized 或 message.sent）
  • data.payload.id （送达的消息 id）
  • data.payload.to.status（可以是 delivered 或 sent）

如果消息发送失败，那么 data.payload.to.status 字段会变成 sending_failed 或 delivery_failed 。

如何配置你的 SIP 线路

  1. 添加一条 Generic 的中继
  2. 配置你的中继的信息。
  3. 在短信界面选择启用 SMS。
  4. 把 3CX webhook 链接复制到线路的门户网站。
  5. 把线路那边生成的 API Key 和 Provider URL 粘贴过来。
Filed Under: 技术文档