12 Dec 17

Improved API References, Content and SSML

Since v1.1.0 we've made many changes across the board to improve our content.

Today we're happy to release a full revision of our SMS content including a new cleaner API Reference page powered by Open API Definitions. We've also made it easier to get started with Nexmo and have built tooling to make complicated subjects such as SMS Concatenation and Encoding easier to understand.

Furthermore here are just a handful of other changes we've made recently:

  • Added SSML documentation
  • Added a Team page
  • Improved Contribution section
  • Lots of improvements to building blocks
  • Added a new footer with helpful links and API status
  • Improvements to search
  • Many hundreds of improvements and fixes to our content and tools

24 Jul 17

Launching Nexmo Developer

After releasing v1.0.0 we reviewed the site for any changes that were required before Nexmo Developer could become our canonical source of documentation for our platform. We created a GitHub milestone  to track these issues thorough to completion. Here's a brief outline of the major changes:

  • Search - With Algolia  we added the ability to search across Nexmo Developer and our Knowledgebase 
  • IA Tweaks - API references are now shown alongside the product in Documentation
  • Contribute - The start of a new Contribute page listing various ways you can get involved with Nexmo Developer & Suggest an edit links to content pages making it easy to find the documentation source.
  • Changelog - Added this changelog page... how very meta.
  • Bugs and content tweaks - Fixed several bugs and improved content throughout Nexmo Developer

19 Jun 17

Introducing Nexmo Developer

Nexmo Developer is the new home for our documentation, API references, community content and resources. Our team has been working hard to improve our developer experience: whether you're new to Nexmo APIs or a well accustomed with our platform and tooling, the new Nexmo Developer site makes life easier for you to find what you need to work with our platform.

We will continue to iteratively improve on Nexmo Developer and provide new and innovative ways to help you implement Nexmo APIs into your products quickly, confidently and efficiently.

A bit of history

Having great tooling is incredibly important for being agile, iterative and innovative. Prior to Nexmo Developer, the documentation for Nexmo APIs was at, a site that has served its purpose well over the last four years.

As we looked to evolve our documentation beyond just guides, our mostly statically-generated site documentation site didn't seem like the best option for moving forward with. We needed something to accelerate us, have the power to be dynamic but retain the simplicity that we've come to love from file-based static site generators.

Our Goals

In January 2017, we started planning out an information architecture that would make content in Nexmo Developer easy and intuitive to find, and to provide consistent content across our products.

We arranged distinct content types such as Documentation, Tutorials and API Reference in our top navigation providing quick and direct access to the most appropriate content for your stage of development.

We then arranged our documentation to be organised by product (Messaging, Voice, Verify and Number Insight), each of which contains the following sections:

  • Overview - A quick look at what the product is and its capabilities including an example quick start implementation
  • Guides - In depth articles about specific product features
  • Building Blocks - Quick access code samples to help you construct your programmable communications apps
  • Tutorials - Step-by-step tutorials to help you build common communications use cases
  • Reference - The resources, parameters and payload examples

Alongside this we created a collection of values that would provide a clear direction for us going forward:


Developer centric

Easy to navigate and consistent




Canonical and Versioned


We've made great progress towards making these goals a reality and will continue to iterate and improve on our platform and share our findings along the way. We'd love to hear your feedback so please feel free to open an issue  if you've got any suggestions on how we can improve Nexmo Developer.

What we've done so far

We've got a lot planned for the future of our content, but given our breadth of products, it was important to take what we had already and make it much more accessible, readable and discoverable.

Alongside the guides that we transitioned we created new overview pages for all of our products making it easy to understand their capabilities and to help developers to find the information they needed as easily as possible. We also introduced 'building blocks' as a quick reference to common practical implementations. We hope you'll find these as useful resources during discovery and development phases.

We moved API references into its own section, and by adding a side navigation, it's easier than ever to find the content you need and keep track of where you are when you are context shifting between Nexmo Developer and your codebase.

Lastly, we've created a new community section with support for videos, and information on the events where you'll find our team attending, sponsoring or speaking. We're excited to grow this to be a hub of community driven content in the future.

From a technical standpoint, we made Nexmo Developer simpler to contribute to by providing contributing guidelines, by making our platform more predictable and by simplifying many aspects of the Markdown source documents.

Technical approach

We built Nexmo Developer as an open-source platform, using a mix of Ruby on Rails, HTML, JavaScript (ES7 + Webpack), Sass and a document parser that extends Markdown with extra functionality useful for writing technical content. All of the tooling and documentation is available for you to contribute to or remix for your own project.

The documentation content is file-based, making it easy for anybody to contribute even within GitHub's own code editor with Markdown support. Alternatively, you can clone Nexmo Developer locally and run it in your own development environment; we even have Docker support to make setup easy and self-contained.

Why Open-source?

Nexmo Developer was built with collaboration in mind. Anybody should feel welcome to contribute to our platform or content. We've created a tool that enables technical writers to easily and simply enhance documentation with supporting content such as tabbed code examples, UML sequence diagrams and much more.

Throughout our research and development we've spoken to various other technical writers and through these discussions believe we've built a platform with a strong foundation with a healthy balance of simplicity and power. We wanted to share this tool with others, to give back to the incredible open-source community and to enable anybody to contribute however they think they could add value.

You can find Nexmo Developer on GitHub 

What next?

In the short term, we'll be reviewing our content and improving our code examples to be more consistent and to use our Libraries. We'll shortly be adding search support helping you find content more quickly across Nexmo Developer and our Knowledgebase  .

In the future, we'll be looking to revise our API Reference and have it powered by OpenAPI Specification  to be consistent, simpler to navigate and easier read. We've also got a lot of ideas about personalising documentation examples and adding interactivity to our tooling where appropriate to enrich our learning resources.


We've come a long way, but we've got much to do and improve. We hope that the steps we've made will have a positive impact on you and your teams' productivity when integrating with Nexmo.

As always we welcome feedback. Please let us know using the feedback tool (👍👎) at the bottom of each guide or file an issue  on GitHub.