Overview #

Binds are routes messages flow through the Lark Router, there are two categories. Client Binds and Supplier Binds. Client Binds route messages into Lark Router. Supplier Binds route messages out of the Lark Router to be delivered. Routing information will be provided by the partners sending message traffic.

How to configure a Lark Client Bind #

To configure a route into Lark Router, choose Binds go to Clients, choose SMS or MMS and then click Add Bind.

Enter the Bind ID, the Bind Names. Choose the type of bind MM7 MMS, MM4 MMS or HTTP, HTTP SMS, or SMPP SMS  (see above for a description of the bind types) and click Add Bind.

You may now click on the Bind ID to edit the bind with the settings supplied by the provider. Not all settings will show for all protocols, only protocol-specific values will be displayed,

General

Bind ID: Unique Name given to the bind when created

Bind Type: Protocol used for the bind chosen upon creation.

Bind Name: Short Name given to the Bind, this can be changed after creation if needed.

SMS API Type: HTTP SMS Bind types only, specifies the kind of SMS API (Twilio, NexMo, etc.)

IP Restrictions: Used to block IP Addresses from the submitting messages.  

Provide this Connection Information/URL To The Client: This is the URL the provider will use to send MT to the gateway. 

MO & DLR Settings

Enable MO & DLR: Enable this if the gateway should deliver MO and DLR to the provider, otherwise, they will be discarded. 

MO URL: The Full Client MO URL provided by the client (MM7 only).

SMTP Host & Port: IP and Port address for SMTP (MM4)

MO Credentials: Username and Password for accessing the above URL. (Uses HTTP Basic Authentication.)

DLR URL: URL to submit delivery reports to. If not set, then the MO URL will be used. Used for MM7 MMS, HTTP MMS, and HTTP SMS.

DLR URL Credentials (optional): The username and password to use to access the DLR URL (if set).

Limit per-second connections to Client to: Set if the client has a limit to how many new connections per second can be created. HTTP-based APIs only.

Use Secure SMTP for MT: MM4 only, whether to use secure connections (TLS/SSL) for outgoing connections to the client’s SMTP host & port.

Strip Type Indicator From MM4 Recipient: MM4 Only, normally the receiver number in the MM4 MO is specified as 12345/TYPE=PLMN@mm4domain.com. However, some MM4 Clients do not support this format. When this flag is set, the receiver is sent as 12345@mm4domain.com

MT Settings

MT Credentials (Optional): The credentials the client must use to authenticate to the gateway when sending MT messages. 

Limit per-second connections to Client to: Set if the supplier has a limit to how many new connections can be created.

Limit # of Concurrent Connections from Client to: Maximum concurrent connections allowed from the client. This is for HTTP-based connections only.

Limit Client Throughput to: Per second rate the client is allowed to send messages.

Maximum MT Message Priority: Gateway will limit the message priority on this bind to this value. This is for MMS binds only.

SMPP Client Credentials: System ID and Password for client SMPP connections to the gateway.

SMS to MMS Conversion: HTTP SMS and SMPP client binds only. Specifies whether to convert MT SMS to MMS, for such things as Ad Campaigns, etc. See here for more information on how SMS MT messages are converted to MMS.

Default SMS Character Encoding: SMPP binds only, this is the default coding scheme when none is provided in the SMPP packet. The default is UTF-8.

Optional SMPP Parameters: Optional, if vendor-specific TLV parameters must be included in the deliver_sm/data_sm SMPP packets sent to the client, they should be set here.  

MM7- Specific Settings (Advanced/Optional)

MM7 Version: MM7/SOAP Version number to be used.

MM7 XML Namespace: Optional, provided by the client.

Use Strict XML Namespace Prefixes on SOAP Tags.  Some clients require strict XML formatting of SOAP requests, such as using namespace prefixes on all tags. Set this if that is required.

Require Client to Process All SOAP Elements: Set to true to include the mustUnderstand attribute on the SOAP Envelope XML tag, to require that the client processes all SOAP elements.

Send Customer MO/DLR information to Client using HTTP:  When set, the Client will receive custom information from the server (e.g. timestamps) using custom HTTP headers. See here. for more details.

Content Transfer-Encoding: Binary or Base64. This specifies the SOAP attachment content transfer encoding. Base64 (the default) is more widely-supported, however binary, if supported by the client, results in 30% smaller HTTP packets and therefore faster throughput.

Advanced Settings

What to Log: Use default or change just for this bind.

Allow Client to Specify Supplier Route in MT Requests:  Optional, when enabled, the client may specify the supplier route within the MT request. For MM7 clients, the supplier bind ID is specified using the HTTP request header X-MMSC, for HTTP MMS clients, the mmsc CGI request parameter is used. Default is `false`.

Send Intermediate DLR to the client: When set, non-final DLR (e.g. delivery to the supplier) also reported to the client. Default is only to send final DLR (expired, delivered, failed, etc.)

Allow Client to set the carrier bind Authentication Parameter using HTTP Extension Headers:  When enabled, the client is allowed to specify the supplier MT credentials using HTTP request headers X-Lark-MMSC-UserName and X-Lark-MMSC-Password respectively. This applies to HTTP-based clients and sets the credentials for HTTP-based suppliers.

How to configure a Lark Supplier Bind #

To configure a route from the Lark Router to a destination, choose Binds, then Suppliers and click Add Bind. Here you will be able to enter the information given by the destination provider.

Enter the Bind ID, the Bind Names. choose MM7, MM4 or HTTP, HTTP SMS, MM1, or SMPP SMS and click Add Bind.

You may now click on the Bind ID to edit the bind with the settings supplied by the provider. Not all settings will show for all protocols, only protocol-specific values will be displayed,

General

Bind ID: Unique Name given to the bind when created

Bind Type: Protocol used for the bind chosen upon creation.

Bind Name: Short Name given to the Bind, this can be changed after creation if needed.

Group ID: Optional, Group ID’s can be used to group binds together for load balancing.

SMS API Type: HTTP SMS Bind types only, specifies the kind of SMS API (Twilio, NexMo, etc.).

MM1 Notification API Type: The SMS API to use for sending MM1 notifications (SMPP, Twilio, NexMo, etc.). For MM1 bind types only. The actual SMS API parameters are set in the MM1 Notifications Settings section when the API type is selected.

MT Settings 

URL: Supplier provided URL for MT messages. For HTTP-based bind types only.

MT Authentication: Username and Password provided by the supplier for authenticating the gateway to the supplier’s endpoint.

Use HTTP Keep-Alive: Enabled HTTP Keep-alive header to ensure connections are re-used. HTTP-based bind types only.

VASP ID: MM7/SOAP VASP ID parameter.

MT Recipient Number Normalization Rules: The bind-specific normalization rules for the receiver number. If not provided, the system defaults (see above) are used.

Limit MT Throughput to: If there is a maximum message throughput imposed by this supplier, set it here.

Maximum MT Message Size: If there is a maximum message packet size set by the supplier, provide it here. The gateway will discard all MT that exceeds this size. 

Limit # of Concurrent Connections to the supplier to: Maximum concurrent connections allowed to this supplier. HTTP-based binds only.

Limit per-second connections to Client to: Set if the supplier has a limit to how many new connections can be created. HTTP-based binds only.

Optional Network timeout Settings (Seconds)

Connection Timeout: How many seconds to wait for a connection attempt to succeed. Default 600 Seconds

Response Timeout:  How many seconds to wait for a response to a request, default is 600 seconds.

SMTP Host & Port (MM4): MM4 end-point. Should be in the form host:port – if the port is not provided, 25 is assumed for plain MM4, 465 for SSL/TLS. MM4 binds only.

MM4 Domain (MM4): Optional. This is the domain part (after the @ in the email) of the supplier,  to be used for MT requests, and to authenticate inbound messages (if user/password not provided). If it is not provided, then the SMTP host is used.  MM4 Only.

Use Secure SMTP: Whether to use TLS/SSL when connecting to the Supplier to send MT MMS. MM4 Only.

Ignore STARTTLS SMTP Option (MM4):  When set, STARTTLS will not be used in the outgoing MM4 transaction, even if the supplier MM4 endpoint advertises that it supports it. This is useful for buggy SSL/TLS implementations, and for connections over VPNs which do not need additional TLS encryption. By default, the gateway always issues the SMTP STARTTLS command on outgoing connections if the endpoint advertises support for it.

Strip Type Indicator From MM4 Recipient (MM4): Normally the receiver number in the MM4 MT is specified as 12345/TYPE=PLMN@mm4domain.com. However, some MM4 suppliers do not support this format. When this flag is set, the receiver is sent as 12345@mm4domain.com

SMSC Host: MC host. SMPP binds only.

SMSC Port: MC port provided by SMPP Supplier, and whether the connections are over SSL/TLS

SMPP Client Authentication: System ID and Password for SMPP bind only.

SMPP Parameters

 These settings are for SMPP supplier binds and MM1 suppliers where the SMS API is SMPP.

SMPP Connection Type: Whether the gateway should bind to the MC in transceiver (Send & Receive), receiver (Receive Only) or transmitter (Send Only) mode.

SMPP Version: Default is 3.4

SMPP System Type Parameter: Optional system type, e.g. VMA, OTA

Sender Number Type: This the SMPP sender number TON setting.

Sender Number Plan Indicator: This is the SMPP sender NPI setting.

Destination Number Type: This the SMPP destination number TON setting.

Destination Number Plan Indicator: This is the SMPP destination NPI setting.

SMSC Message-ID Format: Some SMSCs use a different format of the message ID in the submit_sm_resp SMPP PDU (i.e. MT SMS Ack) from that used in the DLR (deliver_sm PDU). By default, message IDs are opaque strings, however, some supplier SMSCs use decimal-valued message IDs, while others use hexadecimal-valued message IDs. Some switch between these two formats, with the initial ACK containing one format, and the DLR containing a different format. Use this to specify whether SMPP Gateway should perform any conversion on the message ID before performing DLR matching. 

• Default (opaque string)
• Decimal (Both DLS/MT Ack)
• Decimal in DLR, Hex in MT Ack
• Hex in DLR, Decimal in MT Ac)
• Hex in DLR, Hex in MT Ack

Link Check Interval (secs): This is the number of seconds between each enquire_link PDU, sent to check that the connection is alive. 

Maximum # of Unacknowledged Messages:  Optional. If the SMSC requires synchronous message submission, set this to 1. by default the gateway sends messages as fast as possible (subject to throughput setting), without waiting for message acknowledgment from the SMSC. This is usually fine since SMPP is asynchronous. If the supplier SMSC sets restrictions on how many message acks (submit_sm_resp PDUs) must be outstanding, you should set that here to avoid errors.

Optional SMPP Parameters:  Optional SMPP TLV Parameters for the bind, which will be included in all submit_sm packets sent. 

MO & DLR Settings 

MO URL: The gateway MO URL to be provided to the supplier. HTTP-based binds only.

MO Credentials: Username and Password for accessing the above URL on the gateway.

Limit Supplier MO/DLR Connections by IP:  Optional White list IP addresses from which the supplier can initiate MO to the gateway.

Maximum MO Message Size (Megabytes): Limit the message size we received from the supplier. For MM4 this would be email size, anything larger will be discarded.

MO Sender Normalization Rules: MO sender number normalization rules specific for this supplier. Optional otherwise we default to a system-wide setting.

Default MO MMS Validity (Days): This is the message expiry period used by the gateway if none is supplied in the MO from the supplier. The system-wide default is used if left empty or set to zero.

Maximum MO MMS Validity (Days): MO MMS validity is capped at this if set. Set to zero, or leave blank to use the system default.

MM1- Specific Settings

MM1 Message Download Host Address: The MM1 host to be used in creating the notification URL. If the license restricts this hostname, then it cannot be changed here.

Use HTTP-based Notification URL: Whether to use HTTPS rather than HTTP in the notification URL. This requires that the supplier MM1 HTTPS port has been configured.

Perform Content Adaptation: Whether media in the MT MMS should be downsampled as necessary if the subscriber device’s profile indicates that it does not support the content format or size (e.g. video codec, etc.). The settings below control content adaptation further. How content adaptation works: The gateway examines the device’s user agent profile and determines the video, image and audio codecs, bit rates, and durations supported. 

• Audio: If the MT MMS contains audio content that is not supported by the device (e.g. wrong bitrate or it is too large), the gateway attempts to convert the content to AMR for the device, if the device supports AMR. Otherwise, the MMS MT is discarded. If the 
• Text: If the MT MMS contains text using a character set that is not supported by the device, the gateway converts the text to UTF-8.
• Image: If the MMS contains an image that is not supported (e.g. it is too wide or too tall or is in an unsupported format), the gateway converts it to a 640px-wide JPEG (while maintaining the aspect ratio). If the device does not support JPEG, the MMS is discarded.
• Video: If the MMS contains an unsupported video format (e.g. codec or size is unsupported), the gateway converts the video to 3GPP video and audio. If the device does not support this format, the MMS is discarded.

Minimum Video Bitrate: Optional minimum video bitrate when content adaptation is performed. Any video with a lower bitrate than this will never be downsampled, regardless of the device’s profile. The default is 400kbps. 

Only Adapt/Downscale Videos With a Max. Duration Of : Do not downsample videos longer than this number of seconds. The default is 30.

Minimum Audio Bitrate: Do not downsample audio content with a lower bitrate than this. Default is 8kbps.

Send Delivery Report When MMS is Downloaded: When set, the gateway will send a DLR when the device fetches/downloads the MMS, rather than waiting for the device to send the download acknowledgment.

Track Notification DLRs: Turn this on so that when notification SMS is delivered to the device, the gateway can generate DLR.

Notification DLRs To Track: Specify which notification SMS DLRs to report to the client.

HTTP Header Containing MSISDN: When the subscriber device fetches the MT MMS, it must identify itself. This is done using an HTTP request header (by convention/default X-WAP-Network-Client-MSISDN). 

MM7-Specific Settings (Advanced /Optional)

Default VAS ID: The MM7/SOAP VAS ID parameter sent in the MT message if none was supplied when the MT was sent by a Client

MM7 Version: MM7/SOAP Version number

MM7 XML Namespace: Optional, provided by the supplier,

Some clients require strict XML formatting of SOAP requests, such as using namespace prefixes on all tags. Set this if that is required.

Require Client to Process All SOAP Elements: Set to true to include the mustUnderstand attribute on the SOAP Envelope XML tag, to require that the client processes all SOAP elements.

Skip SenderAddress Tag: When set, the SenderAddress SOAP Tag is not included in the MT Message.

Always Use ShortCode Tag in Sender: When set, the sender number is always labeled as ShortCode. This is useful in cases where the receiving Supplier expects this tag for identification purposes

Content Transfer-Encoding: Binary or Base64. This setting behaves in the same manner as that for MM7 clients.

Retry MT After These MM7 Error Codes: Comma-separated. When any such MM7 status error is received, the MT will still be retried.

Additional MM7 Response Codes Treated as Success: Optional list of numeric MM7 response codes which, when received from the MMSC, are also treated as a success. Normally only the 1000 response code is considered as signaling successful MT handover to MMSC.

MM7 Throttle Indication Response Code: Optional. When set, the MMSC can use this MM7 response code to indicate Lark to slow down MT transmission. Lark will then wait a few seconds before trying to send again on the same bind. 

Supplier Bind ID HTTP Header Name in MO Request: Supplier indicator HTTP Header. Optional. This can be used to indicate to the supplier additional routing information as provided by the client.

Default Supplier Bind ID: Supplier Bind ID to report to Client when none is provided in MT request from the client. Optional 

Advanced/Optional Settings

Dedicated MO/DLR Port: Optional. When provided, the gateway will open the port and receive MO messages and DLR on it. HTTP-based binds only

Cache DLR Callback URL Info For: Optional. When a DLR callback URL is specified during MT MMS submission, it will be stored for at most the number of days specified above. The default is to store it forever.  

What to Log: Use default or change just for this bind. Discard all MT Requests: When set, MT messages are never submitted to the Supplier. All MT are black-holed and a generated message ID is returned to the sending client.