Aller au contenu principal

Quick Start for Summarization

In this guide, we'll walk you through how to get started with the Summarization endpoint of the Agent Assist API, including both Synchronous and Asynchronous methods. These endpoints allow you to summarize customer inquiries or text input based on the type of summary requested.

Synchronous Summarization​

This method returns the summarized text immediately after processing. It is ideal for small inputs that do not require extended processing time.

Step 1: Prepare the Payload​

To summarize text synchronously, prepare a request payload with the text to be summarized and the desired summary type.

Here’s an example of a synchronous request payload for a factual summary:

{
  "text": "Nelson Mandela served 27 years in prison, split between Robben Island, Pollsmoor Prison, and Victor Verster Prison. Amid growing domestic and international pressure and fears of racial civil war, President F. W. de Klerk released him in 1990. Mandela and de Klerk led efforts to negotiate an end to apartheid, which resulted in the 1994 multiracial general election in which Mandela led the ANC to victory and became president. Leading a broad coalition government which promulgated a new constitution, Mandela emphasised reconciliation between the country's racial groups and created the Truth and Reconciliation Commission to investigate past human rights abuses.",
  "type": "factual_summary"
}

Step 2: Send the Request​

Once your payload is ready, send it via a POST request to the following endpoint:

Endpoint: POST /api/companies/{companyCuid}/orchestrators/{orchestratorCuid}/summarization

Example cURL Request:

curl -X POST https://api.dialonce.ai/agent-assist/v1/companies/{companyCuid}/orchestrators/{orchestratorCuid}/summarization \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Nelson Mandela served 27 years in prison, split between Robben Island, Pollsmoor Prison, and Victor Verster Prison...",
    "type": "factual_summary"
  }'

Step 3: Handle the Response​

The response will contain the generated summary immediately. Here's an example of a successful response:

{
  "markdown": "**Nelson Mandela** served 27 years in prison before his release in 1990 by President F. W. de Klerk. Together, they negotiated an end to apartheid, leading to South Africa’s first multiracial election in 1994, where Mandela became president. His government promoted reconciliation, established the Truth and Reconciliation Commission, and maintained a liberal economic framework while implementing reforms in land, poverty reduction, and healthcare. Internationally, he mediated the Pan Am Flight 103 bombing trial and led the Non-Aligned Movement (1998–1999). Declining a second term, he was succeeded by Thabo Mbeki and later focused on poverty and HIV/AIDS through the Nelson Mandela Foundation."
}

Asynchronous Summarization​

This method is ideal for longer text inputs or when extended processing time is required. It allows you to process large documents asynchronously, so you can continue with other tasks while waiting for the summary to be ready.

Step 1: Prepare the Payload and send the request​

To summarize text asynchronously, prepare a request payload within the field "content" with the text to be summarized and the desired summary type.

For an asynchronous summarization request, send a POST request to the following endpoint: Endpoint: POST /api/companies/{companyCuid}/orchestrators/{orchestratorCuid}/summarization-async

Example cURL Request:

curl -X POST https://api.dialonce.ai/agent-assist/v1/companies/{companyCuid}/orchestrators/{orchestratorCuid}/summarization-async \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content":
      {
        "text": "Nelson Mandela served 27 years in prison, split between Robben Island, Pollsmoor Prison, and Victor Verster Prison. Amid growing domestic and international pressure and fears of racial civil war, President F. W. de Klerk released him in 1990. Mandela and de Klerk led efforts to negotiate an end to apartheid, which resulted in the 1994 multiracial general election in which Mandela led the ANC to victory and became president. Leading a broad coalition government which promulgated a new constitution, Mandela emphasised reconciliation between the country's racial groups and created the Truth and Reconciliation Commission to investigate past human rights abuses.",
        "type": "factual_summary"
      }
    }'

You can link your process with an external ref as well as external metadata. For more information, please take a look at the endpoint documentation.

Step 2: Get the Result​

After the process is initiated, you will receive a process_cuid that you can use to check the status and get the result.

Example Response After Initiating Async Request:

{
  "process_cuid": "1234567890abcdef"
}

You can use this process_cuid to check the status and retrieve the final result with the following GET request:

Endpoint: GET /api/companies/{companyCuid}/orchestrators/{orchestratorCuid}/summarization/{processCuid}

Example cURL Request:

curl -X GET https://api.dialonce.ai/agent-assist/v1/companies/{companyCuid}/orchestrators/{orchestratorCuid}/summarization/{processCuid} \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN"

Example Response:

{
  "result": {
    "markdown": "**Nelson Mandela** served 27 years in prison before his release in 1990 by President F. W. de Klerk. Together, they negotiated an end to apartheid, leading to South Africa’s first multiracial election in 1994, where Mandela became president. His government promoted reconciliation, established the Truth and Reconciliation Commission, and maintained a liberal economic framework while implementing reforms in land, poverty reduction, and healthcare. Internationally, he mediated the Pan Am Flight 103 bombing trial and led the Non-Aligned Movement (1998–1999). Declining a second term, he was succeeded by Thabo Mbeki and later focused on poverty and HIV/AIDS through the Nelson Mandela Foundation.",
    "html": "<!DOCTYPE html>\n<html>\n<head>\n  <meta charset=\"UTF-8\">\n  <title>Nelson Mandela Summary</title>\n</head>\n<body>\n  <p><strong>Nelson Mandela</strong> served 27 years in prison before his release in 1990 by President F. W. de Klerk. Together, they negotiated an end to apartheid, leading to South Africa’s first multiracial election in 1994, where Mandela became president. His government promoted reconciliation, established the Truth and Reconciliation Commission, and maintained a liberal economic framework while implementing reforms in land, poverty reduction, and healthcare.</p>\n  <p>Internationally, he mediated the Pan Am Flight 103 bombing trial and led the Non-Aligned Movement (1998–1999). Declining a second term, he was succeeded by Thabo Mbeki and later focused on poverty and HIV/AIDS through the Nelson Mandela Foundation.</p>\n</body>\n</html>"
  },
  "status": "finished",
  "error": "null",
  "external_ref": "1234ef6789"
}

Example Failure Response :

If the process fails, the status will be failed, and the error message will appear in a field called error.

{
  "status": "failed",
  "error": "An error occurred while processing the request. Please try again later."
}

In this case, you'll receive an error message to help identify what went wrong. Make sure to handle failure scenarios appropriately in your application.

Next Steps​

Now that you've seen how to make a basic request, you can explore more advanced options: