Configuration

Core #

Host Name

  • DNS Name This is the hostname for the instance on which Lark Is running (And licensed for. It is also the MM4 Domain.

Logging and Errors

This section contains logging settings.

  • Where to Log– Server directory where to store system logs.
  • What to log 
    • Everything (Debug) -Should only be used for debugging as it will increase log size.
    • Informational Messages- This will show warnings, errors, and informational messages.
    • Warnings & Errors Only- Just the warning and error messages.

SSL Certificates and Keys

This section contains a secure client and server certificate and private key settings. 

SSL/HTTPS Server Certificate: If protocol traffic (such as MM7, MM4, or SMPP) will be transmitted over secure network ports, the PEM-encoded SSL certificate must be provided.

SSL/HTTPS Server Private Key: This is the PEM-encoded SSL private key associated with the SSL certificate. The private key must not be password protected. 

SSL/HTTP Client Certificate & Private Key: If Lark Router must identify itself to external services using an SSL certificate when initiating protocol requests (e.g. MM7 or MM4), the PEM-encoded client SSL certificate and associated private key must be provided. The private key must not be password protected.

HTTP Settings

This section contains system-wide HTTP protocol settings.

HTTP Client Request Timeout (seconds): HTTP requests to external services that take too long are abandoned, this setting customizes how long Lark router waits for HTTP responses (e.g. to MM7 requests).

HTTP Server Timeout (seconds): HTTP connections to the Lark router that take too long to send a request are abandoned, this setting customizes how long Lark router waits for full HTTP request (e.g.  MM7 requests to Lark).

HTTP Proxy Host: If a HTTP PRoxy is needed for HTTP requests (e.g. MM7), enter it here.

Databases #

This section contains storage database settings.

REDIS Cache Server

REDIS Server Host & Port: Location of the REDIS Server if not using the default

RabbitMQ Server

HOST: Location of the RabbitMQ Database if not the default.

Port: Port number to access the database and whether it is using SSL/TLS

Credentials: Username and Password for RabbitMQ Database.

Queues, CDR and Caching #

This section contains queue management configuration information such as storage locations, process frequency, retry intervals, delivery attempts, message validity, etc.

Queue Management

  • MMS Binary Storage Location: Where Lark Router MMS binary files are stored.
  • Maximum Submit Attempts: If an outbound message such as MT MMS cannot be sent (e.g. due to the external service reporting an error), Lark Router will retry this number of times before reporting an error.
  • On Message Submit Failure retry after: If an outbound message such as MT MMS cannot be sent, this setting specifies how long to wait before retrying delivery.
  • Default Message Validity: If the MT or MO MMS submitted to Lark does not have a validity period set, this setting will be used.
  • Maximum Message Validity: System-Wide cap on message validity for all MT and MO MMS. 
  • Priority Factor: Optional.  This is used to control the priority for client MT messages: The gateway maintains statistics on the number of outgoing messages to each supplier bind, grouped by VAS ID. When a client injects a new message, the stats are consulted to determine the priority to assign the new message: If the outgoing queue length for the current VAS ID is less than factor ⨉  the supplier bind throughput, then the gateway checks if there is at least one VAS ID on the bind that has a larger outgoing queue than the current VAS ID. If there is, then the injected message can be given a slightly higher priority, to ensure it is not blocked/delayed. This priority is calculated as follows: A count is made of all VAS ID queues on the same bind whose outgoing queue length is greater than the queue size for this VAS ID. The new message is given a priority of 4 + the count. (Standard MMS priority values are 0=Low, 1=Normal, 2=High. 4 is used since it is always higher than any normal MMS priority.) This ensures that all VAS IDs that are not performing large message submissions are prioritized over the heavy users, with the slower-pushing VAS IDs getting higher priority. The higher the priority factor on a bind, the more we allow slow senders to lag behind the high throughput senders. The default Priority Factor is 10.

Billing and CDR Processing

This section contains call detail records and billing configurations.

  • How Long to Store CDR: Number of days to keep the CDR’s on the Lark Router
  • External CDR Webhook API URL: Offload CDR’s to another location (Refer to CDR Logging Webhook API Section for more details)
  • External Billing Webhook API URL: Call third-party billing API to charge for messages, (Refer to Billing Webhook API Section for more details)

Content Cache Control Settings #

This section contains content cache control settings. The content cache is used for the temporary storage of MMS content, such as images and videos fetched from external URLs when MMS content is created from SMIL files submitted to Lark.

  • Cached Content Storage Directory– MMS content cache location
  • Max Time to Live– The maximum length of time content can stay in the cache before it must be refreshed (i.e. re-fetched from the original content URL).
  • Automatically Purge Unused Content after – Remove all content from the cache that has not been accessed/used after a period of time.

Protocols and Ports

Supplier Ports and Services  #

This section contains supplier-facing network port configurations.

HTTP MO/DLR Port: Suppliers use this port to send MO and DLR messages into Lark where the supplier protocol is HTTP-based. This includes MM7/SOAP, HTTP-based SMS APIs (such as Twilio). 

MM4 MO/DLR Port: MM4 MMS suppliers use this port to send MO and DLR messages into Lark.

MM1 Ports: Secure/insecure MM1 MO and MT ports.

Restrict MM4 Request to Network Interface:  If the server has multiple IP addresses/network interfaces,  Lark can be configured to receive MM4 requests on a specific IP address/network interface. By default, Lark receives MM4 requests on all server addresses.

Restrict MM1 Request to Network Interface: If the server has multiple IP addresses/network interfaces,  Lark can be configured to receive MM1 requests on a specific IP address/network interface. By default, Lark receives MM1 requests on all server addresses.

Clients Ports and Services #

This section contains client-facing network ports settings.

HTTP MT Port: Clients use this port to send MT  messages into Lark where the client protocol is HTTP-based. This includes MM7/SOAP, HTTP-based SMS APIs (such as Twilio). 

MM4 MT Port: MM4 MMS clients use this port to send MO and DLR messages into Lark.

SMPP Ports: SMS clients use these ports to send SMS MT to (and receive MO/DLR from) Lark using the SMPP protocol. 

HTTP Administration API #

This section contains the Lark Router Gateway administration interface configurations. 

Admin Port: Lark gateway HTTP admin port

Admin Password: Password for accessing Admin API

Whitelist IP: IP addresses that are allowed to access the Admin port

SMPP TLV TAG→ MM7 Field Mappings #

This section contains configurations for SMS to MMS conversion.  SMPP custom TLVs can be used in the MT SMS to specify MM7 VAS ID parameters. 

VAS ID Lark Specific Optional Parameter Code: The SMPP TLV Tag containing the MM7 VAS ID value in the MT SMS. This is used for SMS to MMS conversion only.

MM1-Specific Settings #

This section contains MM1 MMS configurations.

MM1 Host/IP: Required MM1 Notification Host or IP Address. This is used to create the MM1 notification URL. Note that if the license restricts the MM1 hostname, these settings cannot be changed. 

Optimize Notification SMS Size: When set, the MM1 notification SMS does not contain optional data fields (e.g. MMS Subject, date, etc.) so that it is as small as possible.  

Send DLR Once MT MMS Message is downloaded by the recipient: When set, the “Retrieved” DLR is queued back to the client as soon as the subscriber downloads the MMS. By default, this DLR is normally only sent once the subscriber device sends back a positive MMS Ack notification (M-Acknowledge.ind packet).

Track Notification SMS DLR: By default, MM1 notification SMS DLR are not tracked/reported. Set this to request SMS DLR for each MM1 notification sent, and reported as MMS DLR (i.e. failed notification DLR is equated to failed MMS DLR, delivered notification DLR is equated to an intermediate MMS DLR).  

When Notification is Sent, delete queue entry after: Number of days to keep the MMS entry in the queue, after the MM1 notification has been sent. This setting helps ensure the MM1 queues do not hold more entries than is essential.

When MT MMS is Retrieved, delete queue entry after: Number of days to keep the MMS entry in the queue, after the MMS has been retrieved. This setting helps ensure the MM1 queues do not hold more entries than is essential.

When Notification is Sent, delete stored MMS binary after: Number of days to keep the MMS binary file, after the MM1 notification has been sent. This setting helps ensure the MM1 data storage does not hold more entries than is essential.

When MT Message is retrieved, delete stored MMS binary after: Number of days to keep the binary file, after the MMS has been retrieved. This setting helps ensure the MM1 data storage does not hold more entries than is essential.

Send Custom Error MMS when MM1 Fetch Comes after the message has Expired: When the subscriber device attempts to download the MT MMS after it has expired (i.e. queue entry has been removed), the gateway usually sends back an error MMS (i.e. the M-retrieve-conf packet X-Mms-Retrieve-Status field is set to Error-transient-message-not-found). When this flag is set, a custom MMS response is returned to the subscriber. The settings below are only available if this flag is set.

Custom Error MMS When MM1 Fetch Comes After Message Has Expired: The MMS binary to return to the subscriber in the above case (i.e. subscriber attempts to fetch an expired MMS). This should be specified as a SMIL file, image, or video. The gateway will convert into an MMS using the content templates provided (see below). You can also provide a binary MMS directly.

Reply With Custom MMS Only After Devices Retries This Many Times: Only send the custom MMS above when the device retries to fetch the expired MMS repeatedly. This setting is useful for buggy MMS clients which may keep retrying to fetch the MMS even when the gateway has indicated that the message doesn’t exist.

Reset Each Device’s Failed Retries Counter After: Number of days to clear (reset to zero) the retry counter above, for each MMS client/device.

Content Conversion Templates #

This section contains SMIL templates for converting different types of content to MMS. These are used for converting images, video, and text to MMS during SMS to MMS conversion (i.e. MT MMS from an SMS client bind) and for MM1 error MMS creation.

Image Only Template (SMIL): SMIL template to use for creating MMS messages from image only content.  Defaults have already been installed so only update if needed.

Image +Text Template (SMIL): SMIL template file to use for creating MMS messages from image and text content (i.e. when SMS contains text + an image URL).  Defaults have already been installed so only update if needed.

Video Only Template (SMIL): SMIL template file to use for creating MMS messages from video content.  Defaults have already been installed so only update if needed.Video + Text  Template (SMIL):  SMIL Template file to use for creating MMS messages from video + text content (i.e. when SMS contains text + a video URL).  Defaults have already been installed so only update if needed.