Module Specification: Contacts

Adding User Variables

The following user variables can be used:

ID	Name	Example	Example Explanation	Required
_C	Country	gb	Country code in ISO 3166-1 alpha 2 format.	Yes
_L	Language	en	Language code in ISO 639-1 format	Yes
_DV	Device	iPhone 7	This is the model of the device.	No
_OS	Operating System	iOS 10.3	The operating system used by the device.	No
_TZ	Time Zone	GMT	Time zone code. A list of time zones can be viewed here .	No
_G	GPS Co-ordinates	53.473997,-2.237334	GPS Co-ordinates in WGS84 format	No

Each user variable is assigned to a hidden object , using the key shown in the ID column. These variables make up the start of our MODL string:

Adding the Record Configuration File

After assiging values to user variables, we must use the MODL *load instruction to load the Contacts record configuration file, you can view it here .

Adding the NUM Record

The final stage is to retrieve the NUM record from the DNS using a NUM lookup and add the record returned to our MODL string. In this example we've retreived a NUM record for the domain numexample.com:

Now we can interpret our MODL string and have a developer friendly unpacked object to work with.

Entity

A NUM record can describe:

• People using the key person
• Group using the key group
• Organisations using the key organisation
• Departments using the key department
• Employees using the key employee
• Locations using the key location

All entities can be described using the following keys:

• Name a string using the key name providing the name of the object
• Contacts, an array with the key contacts containing ways to contact the entity
• Available hours, a specially formatted string or array using the key hours showing when the object is available

In addition to the keys above, it's also possible to describe:

• A person with a short biographical profile, a string using the key bio
• A group with a description, a string using the key description
• An organisation with a motto or slogan, a string using the key slogan
• A department with a description, a string using the key description
• An employee with a job title / role, a string using the key role
• A location with a description, a string using the key description

Contact Methods

An Entity can include contact methods within the contacts list, contact methods can be described with:

• Value, a string or array using the key value or an array with the key lines in the case of address.
• Description, a string using the key description
• Available hours, a specially formatted string or array using the key hours showing when the object is available

The NUM Contacts configuration file automatically adds the following data to each contact method to assist developers when displaying contact methods in clients:

• Prefix, a string using the key prefix – typically used for URL schemes
• Description default, a string using the key description_default – a default value to use for contact methods that do not have a description
• Object Display Name, a string using the key object_display_name – providing a display friendly way to describe a method, e.g. "Telephone"
• Method Type, a string using the key method_type with the possible values core and third_party. Core methods are those which are standardised contact methods and are not exclusive to other platforms, e.g. email, telephone, GPS etc. Third party methods are contact methods which are reliant on third parties – like Facebook, Twitter and more.
• Controller, a string using the key controller which identifies the entity in control of that contact method. For example, the controller of the Facebook contact method is facebook.com. This can be used to fetch an icon for each contact method.
• Value Prefix, a string using the key value_prefix which identifies the entity in control of that contact method. For example, the controller of the Facebook contact method is facebook.com. This can be used to fetch an icon for each contact method.

Links

Links are presented with the key link and can include:

• Description, a string using the key description
• @L, a NUM link which instructs the client to make a further NUM lookup.

Day Descriptor

The day descriptor field offers a range of options:

Time Descriptor

Times must be provided in 24-hour format but are flexible to ensure maximum character efficiency. Both a start time and end time must be set.

Midnight for the start time (start of the day) is 0. Midnight for the end time (end of the day) is 24. Multiple time ranges can be supplied for a day descriptor by separating the times with a comma (,). This can be particularly useful if a location is closed for a brief period during the day, e.g. a lunch hour.

In this example, available hours are set 9am until midday, unavailable between midday and 1pm, available from 1pm until 5pm:

{ "organisation" : { "name" : "NUM Example Co", "contacts" : [ { "telephone" : { "prefix" : "tel://", "display_name" : "Telephone", "description_default" : "Call", "value" : "+441270123456", "hours": { "time_zone_location" : "LON", "available" : [ "[email protected],13-17" ] } } } ] } }

organisation( name = NUM Example Co; contacts[ telephone( prefix = "tel://"; display_name = Telephone; description_default = Call; value = +441270123456; hours = ( time_zone_location = LON; available = [ [email protected],13-17 ] ) ) ] )