Cisco Spark Getting Started: Account, Keys, First API Call

Getting started overview

Cisco Spark, now integrated into the Webex App, provides a programmatic interface through the Webex API. This API allows developers to interact with core Webex functionalities such as messaging, meetings, and calling. The getting started process typically involves several key steps, beginning with account creation and obtaining credentials, followed by making an authenticated API call.

The Webex API utilizes OAuth 2.0 for authentication, which is a standard protocol for secure authorization. Developers will primarily work with access tokens to authorize requests. The process is supported by comprehensive documentation and SDKs for various platforms, including JavaScript, Android, and iOS, simplifying integration into client applications.

Below is a quick-reference table outlining the initial steps to integrate with the Webex API:

Create an account and get keys

To begin using the Webex API, you must first create a developer account. This account provides access to the developer portal where you can manage your applications and integrations.

1. Sign up for a Webex Account: Navigate to the Webex Developer Portal. If you do not have an existing Webex account, you will be prompted to create one. This typically involves providing an email address and setting a password. Existing Webex users can log in directly.
2. Access My Apps: Once logged in, go to the My Apps section of the developer portal. This is where you will register new integrations.
3. Create a New Integration: Click on the "Create a New Integration" button. You will need to provide the following information:
   • Integration Name: A descriptive name for your application.
   • Integration Icon (Optional): An image to represent your application.
   • Description: A brief explanation of what your application does.
   • Redirect URI(s): This is a crucial field for OAuth 2.0. It specifies where Webex should redirect the user after they grant authorization to your application. For development and testing, you might use http://localhost:8080/oauth or a similar local address. For production, this should be your application's public URL. Multiple redirect URIs can be added.
   • Scopes: Select the necessary permissions your application requires. For a simple messaging application, scopes like spark:messages_write and spark:messages_read would be essential. Carefully choose only the scopes your application needs to adhere to the principle of least privilege.
4. Obtain Client ID and Secret: After creating the integration, the developer portal will provide you with a unique Client ID and Client Secret. These credentials identify your application to Webex during the OAuth 2.0 flow. The Client Secret should be kept confidential and never exposed in client-side code.
5. Generate an Access Token: For your first API call, you'll need an access token. The Webex Developer Portal provides a convenient tool to generate a personal access token for testing purposes. On the Getting Started page, after logging in, you can find your personal access token displayed. This token is valid for 12 hours and is suitable for initial testing and making simple API calls directly. For production applications, you will implement the full OAuth 2.0 authorization code grant flow to obtain user-specific, short-lived access tokens.

Your first request

With an access token in hand, you can now make your first authenticated request to the Webex API. This example demonstrates how to send a simple message to a Webex Space (formerly known as a Room) using the Messages API.

Before making the request, you need a Webex Space ID. You can find this by listing your existing spaces or creating a new one through the Webex App. For testing, you can list your spaces using the following API call:

curl -X GET \
  https://api.webex.com/v1/rooms \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

Replace YOUR_ACCESS_TOKEN with the personal access token you generated. The response will include a list of your spaces, each with an id field. Copy the id of a space where you want to post a message.

Now, let's send a message to that space:

curl -X POST \
  https://api.webex.com/v1/messages \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "roomId": "YOUR_ROOM_ID", "text": "Hello from the Webex API!" }'

In this command:

• YOUR_ACCESS_TOKEN is the personal access token obtained from the developer portal.
• YOUR_ROOM_ID is the ID of the Webex Space you retrieved in the previous step.
• "text": "Hello from the Webex API!" is the message content.

Upon successful execution, the API will return a JSON object representing the newly created message, including its ID, creation time, and content. You should also see "Hello from the Webex API!" appear in the specified Webex Space within your Webex App.

This example uses curl for simplicity, but you can replicate this request using any HTTP client library in your preferred programming language, such as Python's requests library or JavaScript's fetch API. For instance, using Python:

import requests

access_token = 'YOUR_ACCESS_TOKEN'
room_id = 'YOUR_ROOM_ID'
message_text = 'Hello from Python via Webex API!'

headers = {
    'Authorization': f'Bearer {access_token}',
    'Content-Type': 'application/json'
}

payload = {
    'roomId': room_id,
    'text': message_text
}

response = requests.post('https://api.webex.com/v1/messages', headers=headers, json=payload)

if response.status_code == 200:
    print('Message sent successfully:')
    print(response.json())
else:
    print(f'Error sending message: {response.status_code}')
    print(response.text)

Remember to replace the placeholder values with your actual token and room ID. This Python example illustrates how to construct the request programmatically, demonstrating the core components of API interaction: setting headers, defining the payload, and handling the response.

Common next steps

After successfully sending your first message, consider these common next steps to further develop your integration:

1. Explore Other API Endpoints: The Webex API offers a wide range of functionalities beyond sending messages. Explore the Webex API reference documentation to discover endpoints for managing meetings, users, teams, and more. For example, you might want to create a new meeting, list participants in a call, or manage user memberships in a space.
2. Implement OAuth 2.0 Authorization Flow: For production applications, relying on a personal access token is not secure or scalable. Implement the full OAuth 2.0 authorization code grant flow. This allows users to securely grant your application access to their Webex data without sharing their credentials directly with your application. This involves redirecting users to Webex for authorization, receiving an authorization code, and exchanging it for an access token and refresh token.
3. Utilize Webhooks: To receive real-time notifications about events in Webex (e.g., new messages, room creations, membership changes), set up Webex Webhooks. Webhooks are essential for building interactive applications that respond dynamically to user actions within Webex. When an event occurs, Webex will send an HTTP POST request to a URL you specify, containing details about the event.
4. Integrate with SDKs: For client-side development (e.g., mobile or web applications), consider using the official Webex SDKs for JavaScript, Android, or iOS. SDKs abstract away much of the complexity of making API calls and handling authentication, allowing you to focus on application logic. They often provide higher-level abstractions for common tasks.
5. Error Handling and Rate Limits: Implement robust error handling in your application to gracefully manage API errors, such as invalid tokens or malformed requests. Also, be aware of Webex API rate limits to prevent your application from being temporarily blocked due to excessive requests. Implement retry mechanisms with exponential backoff if necessary.
6. Review Security Best Practices: Adhere to security best practices, particularly when handling access tokens and user data. Ensure your Client Secret is never exposed, use HTTPS for all communications, and validate webhook signatures to confirm their authenticity, as detailed in the Webex Webhook security guide.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting tips for the Webex API:

• Invalid Access Token (HTTP 401 Unauthorized):
  • Check Token Validity: Ensure your personal access token has not expired. Personal tokens are typically valid for 12 hours. Generate a new one from the Webex API Getting Started page if needed.
  • Correct Header Format: Verify that the Authorization header is correctly formatted as Bearer YOUR_ACCESS_TOKEN, with a space between "Bearer" and your token.
  • Token Scope: Confirm that the token has the necessary scopes for the API endpoint you are trying to access. For example, sending a message requires spark:messages_write.
• Bad Request (HTTP 400):
  • JSON Payload: Check for syntax errors in your JSON request body (e.g., missing commas, unclosed quotes, incorrect field names). Use a JSON linter if unsure.
  • Required Parameters: Ensure all required parameters for the endpoint are included in your request. For sending a message, roomId and text are mandatory, as specified in the Create a Message API documentation.
  • Content-Type Header: Verify that the Content-Type: application/json header is present if you are sending a JSON payload.
• Not Found (HTTP 404):
  • Endpoint URL: Double-check the API endpoint URL for typos. Ensure you are using https://api.webex.com/v1/messages and not a different path.
  • Resource ID: If you are targeting a specific resource (e.g., a roomId), ensure the ID is correct and corresponds to an existing resource that your token has access to.
• Forbidden (HTTP 403):
  • Insufficient Permissions: Your access token might not have the necessary permissions (scopes) to perform the requested action. Review the scopes associated with your integration or personal token.
  • Resource Access: The user associated with the access token may not have permission to access the specific resource (e.g., a private room).
• Network Issues:
  • Internet Connectivity: Ensure your development environment has stable internet access.
  • Firewall/Proxy: If you are behind a corporate firewall or proxy, ensure it allows outgoing connections to api.webex.com.
• Consult Documentation: The Webex API documentation provides detailed error codes and explanations for each endpoint. Always refer to the specific endpoint documentation when troubleshooting unexpected responses.