Module Specification: Contacts

"

Introduction

Contact information on the internet is unstructured and inconsistent. Finding contact information on an organisation's website consumes considerable amounts of time, data, and often requires significant user interaction. Contact information provided by search engines and social media platforms is neither open nor authoritative and is often incomplete and inaccurate.

The Contacts module can be used to store contact data for a person, group, organisation, department, employee, location or folder. Data can be stored hierarchically allowing organisations to store contact information for each of their locations, departments and employees.

Branch records can be used to navigate complex contact information, providing structured machine readable data to help navigate a call centre or support teams.

Status

The Contacts module is currently being finalised, we are inviting members of the technical community to provide feedback on the specification.

Conventions in This Document

The key words "must", "must not", "required", "shall", "shall not", "should", "should not", "recommended", "may", and "optional" are to be interpreted as described in RFC2119 Content on another site..

Author

The Contacts module was created by Elliott Brown Content on another site..

Working with Contact Records

The first step for working with a NUM Contacts record is to turn it into a useful object.

Creating the Object

NUM records are written in MODL and are unpacked into objects by a MODL interpreter Content on another site. with the help of a NUM record configuration file. To successfully unpack the MODL object we must write a MODL string including user variables, the record configuration file and the NUM record itself.

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 Content on another site. format. Yes
_L Language en Language code in ISO 639-1 Content on another site. 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 Content on another site.. No
_G GPS Co-ordinates 53.473997,-2.237334 GPS Co-ordinates in WGS84 Content on another site. format No

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

_C=gb; _L=en; _DV=iPhone 7; _TZ=GMT; _GPS=53.473997,-2.237334
Writing the MODL string: assigning values to user variables.

Adding the Record Configuration File

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

_C=gb; _L=en; _DV=iPhone 7; _TZ=GMT; _GPS=53.473997,-2.237334; *load="http://modules.numprotocol.com/1/rcf.txt";
Writing the MODL string: adding the load instruction.

Adding the NUM Record

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

_C=gb; _L=en; _Q=numexample.com; _D=numexample.com; _DV=iPhone 7; _TZ=GMT; _GPS=53.473997,-2.237334; *load="http://modules.numprotocol.com/1/rcf.txt" @n=1;o=NUM Example Co:Example Strapline:[t=Call us:+441270123456;fb=examplefacebook;tw=exampletwitter;in=exampleinstagram]
Writing the MODL string: adding the NUM record.

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

Understanding the Object

NUM records for the Contacts module describe Entities.

NUM records can be both multi-national and multi-lingual, catering for huge corporations while staying within DNS limits Content elsewhere on this site.. Contact records are designed to serve the needs of all domain owners – from individuals operating blogs, through to huge multi-national corporations with thousands of stores and a sprawling online presence.

Contact records can be organised hierarchically and linked together, enabling a user or machine to navigate structured contact information. Individuals and small organisations may find that they can provide all of their contact information to users in one simple root record.

Whilst it would be possible for many organisations to provide all of their contact information in one large root NUM record, some organisations prefer their contact information to be more organised and structured. For example, a multi-national organisation may need to present a different NUM record to customers in each of the countries they operate in. Some organisations may like to organise their contact information by department – e.g. Sales.

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 Content further down this document. 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 Content further down this document. 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.

Special Formatting

Values for some objects adhere to formatting rules. These values must be interpreted by the NUM client.

Available Hours

This value provides information about the hours that an object is available for during the day. The value is provided with the key av and it can be used to describe any object. This is the field syntax:

av=[day_descriptor@time_descriptor]
The available hours syntax.

Multiple values can be supplied. Settings that are defined later in the array override those defined earlier. In this example, the first setting sets available hours to weekdays 9am - 5pm but the second setting overrides that for Mondays, declaring available hours on Monday as midday - 6pm London time.

{ "organisation" : { "name" : "NUM Example Co", "contacts" : [ { "telephone" : { "prefix" : "tel://", "display_name" : "Telephone", "description_default" : "Call", "value" : "+441270123456", "hours" : { "time_zone_location": "LON", "available": ["wd@9-17", "1@12-18"] } } } ] } }
organisation( name = NUM Example Co; contacts[ telephone( prefix = "tel://"; display_name = Telephone; description_default = Call; value = +441270123456; hours = ( time_zone_location = LON; available = [wd@9-17; 1@12-18] ) ) ] )
  • JSON
  • MODL

Day Descriptor

The day descriptor field offers a range of options:

Descriptor Explanation Example Outcome
d Every day d@9-17@LON Available every day 9am - 5pm
wd Weekdays wd@9-17@LON Available weekdays 9am - 5pm
we Weekend we@9-17@LON Available Saturday and Sunday 9am - 5pm
1 Monday 1@9-17@LON Available Monday 9am - 5pm
2 Tuesday 2@9-17@LON Available Tuesday 9am - 5pm
3 Wednesday 3@9-17@LON Available Wednesday 9am - 5pm
4 Thursday 4@9-17@LON Available Thursday 9am - 5pm
5 Friday 5@9-17@LON Available Friday 9am - 5pm
6 Saturday 6@9-17@LON Available Saturday 9am - 5pm
7 Sunday 7@9-17@LON Available Sunday 9am - 5pm
nh National holidays (user country) nh@0-0@LON Closed on national holidays in the country of the user.
nhcountry National holidays (specified country) nhus@0-0@NYC Closed on national holidays of the United States.
dayno-dayno Day range 1-4@9-17@LON Open Monday - Thursday 9am - 5pm
dayno,dayno Day list 1,3,5@9-17@LON Open Monday, Wednesday and Friday 9am - 5pm
YYYYMMDD A specified day 20181211@0-0@LON Closed on 11th December 2018
YYYYMMDD-YYYYMMDD A specified date range 20181219-20190102@0-0@LON Closed from 19th December 2018 through to 2nd January 2019

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.

Example Explanation
9-17
9.00-17
9.00.00-17.00
09.00.00-17
All are valid and represent exactly 9 AM until 5 PM. The object will be shown as available at 9am and unavailable at 5pm.
9.30-17.30
9.30-17.30
9.30.00-17.30.00
09.30.00-17.30
All are valid and represent exactly 9:30 AM until 5:30 PM. The object will be shown as available at 09:30 and unavailable at 17:30.

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" : [ "wd@9-12,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 = [ wd@9-12,13-17 ] ) ) ] )
  • JSON
  • MODL